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Abstract:  Estimating  nearshore  wave  transformation  and  wind-wave 
growth  is  a  critical  component  of  many  coastal  engineering  projects,  e.g., 
predicting  shoreline  change,  designing  and  maintaining  coastal  structures, 
and  simulating  coastal  storm  events.  Performing  physical  model  studies  or 
gathering  field  data  is  not  always  a  feasible  option,  and,  as  a  result,  the  use 
of  numerical  models  for  simulating  these  complex  coastal  hydrodynamics 
has  become  a  universal  practice. 

STWAVE  (STeady-state  spectral  WAVE),  a  nearshore  spectral  wave  model, 
was  developed  by  the  U.S.  Army  Engineer  Research  and  Development 
Center  (ERDC),  Coastal  and  Hydraulics  Laboratory  (CHL)  to  accurately 
simulate  nearshore  wave  propagation  and  transformation  including 
refraction,  shoaling,  breaking,  and  wind-wave  generation.  Recently,  CHL 
has  further  enhanced  STWAVE  to  include  both  half-plane  and  full-plane 
capabilities  within  a  single  executable;  improved  and  streamlined  file 
formats;  and  made  it  Earth  System  Modeling  Framework  (ESMF) 
compliant,  which  allows  for  easier  coupling  to  other  models.  STWAVE  now 
runs  in  serial  mode  as  well  as  parallel  in  time  or  space  on  both  personal 
computing  (PC)  and  high-performance  computing  (HPC)  systems.  This 
report  describes  STWAVE  version  6.0  capabilities,  features,  theory,  and 
implementation.  In  depth  descriptions  of  model  parameters  and  examples 
of  the  new  file  formats  are  also  provided. 


DISCLAIMER:  The  contents  of  this  report  are  not  to  be  used  for  advertising,  publication,  or  promotional  purposes. 
Citation  of  trade  names  does  not  constitute  an  official  endorsement  or  approval  of  the  use  of  such  commercial  products. 
All  product  names  and  trademarks  cited  are  the  property  of  their  respective  owners.  The  findings  of  this  report  are  not  to 
be  construed  as  an  official  Department  of  the  Army  position  unless  so  designated  by  other  authorized  documents. 
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1  Introduction 

The  purpose  of  applying  nearshore  wave  transformation  models  is  to 
describe  quantitatively  the  change  in  wave  parameters  (wave  height,  period, 
direction,  and  spectral  shape)  of  waves  propagating  from  offshore  to 
nearshore  regions.  Unlike  offshore  waves,  which  are  fairly  homogenous  on 
the  scale  of  kilometers,  nearshore  waves  are  highly  influenced  by  bathy¬ 
metric  features,  currents,  and  fluctuating  water  levels,  and  may  vary  on  the 
scale  of  tens  of  meters.  Offshore  wave  information  obtained  from  wave 
gauges  or  global-  or  regional-scale  wave  hindcasts  or  forecasts  is  trans¬ 
formed  to  the  nearshore  coastal  region  using  these  models.  Nearshore  wave 
information  is  required  for  the  design  of  nearly  all  coastal  engineering 
projects,  and  using  numerical  models  to  estimate  these  parameters  is 
becoming  extensive  due  to  their  increasing  complexity  and  economy  of 
application  relative  to  field  or  physical  model  studies. 

The  purpose  of  STWAVE  (STeady-state  spectral  WAVE  model)  is  to 
provide  a  simple,  robust  numerical  model  for  simulating  nearshore  wind- 
wave  growth,  propagation,  and  transformation  (Smith  et  al.  2001;  Smith 
2001;  Smith  2007).  STWAVE  is  a  finite-difference,  phase-averaged 
spectral  wave  model  based  on  the  wave  action  balance  equation.  This 
report  describes  version  6.0  of  STWAVE,  which  uses  an  improved  file 
format  and  is  able  to  operate  in  half-plane  or  full-plane  mode  with  a  single 
executable. 

This  report  presents  the  general  features,  governing  equations, 
capabilities,  and  guidelines  for  using  STWAVE  version  6.0.  In  Chapter  2, 
model  capabilities  and  assumptions  are  given.  An  overview  of  the 
governing  equations  and  numerical  discretization  of  STWAVE  are 
provided  in  Chapter  3.  Chapter  4  describes  STWAVE  input  and  output 
files  with  a  further  description  of  the  model  parameters  presented  in 
Chapter  5.  Descriptions  of  STWAVE  spatial  and  spectral  data  sets  are  in 
Chapters  6  and  7,  respectively.  Sample  input  and  output  files  are  given  in 
Appendices  A-C. 
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2  Model  Overview 

Model  capabilities 

STWAVE  computes  nearshore  wave  transformation  including  refraction, 
shoaling,  and  breaking,  as  well  as  wind-wave  generation.  STWAVE  has 
two  modes  available,  half-plane  and  full-plane.  Half-plane  mode  allows 
wave  energy  to  propagate  only  from  the  offshore  towards  the  nearshore 
(±87.5  deg  from  the  x-axis  of  the  grid,  which  is  typically  the  approximate 
shore-normal  direction).  All  waves  traveling  in  the  negative  x-direction, 
such  as  those  reflected  from  the  shoreline,  steep  bottom  features,  and 
structures,  as  well  as  those  generated  by  offshore-blowing  winds,  are 
neglected  in  half-plane  simulations.  The  full -plane  mode  allows  wave 
transformation  and  generation  on  the  full  360-deg  plane. 

The  full-plane  option  of  STWAVE  is  not  intended  to  be  a  replacement  for 
the  half-plane  version,  but  an  addition.  The  half-plane  version  requires 
considerably  lower  memory  requirements,  executes  faster,  and  is  generally 
appropriate  for  most  nearshore  coastal  applications  with  the  exception  of 
semi-enclosed  bays  and  lakes  where  there  is  no  obvious  offshore  direction. 
For  these  cases,  the  full-plane  version  should  be  applied  since  it  allows 
wave  transformation  and  generation  in  all  directions.  Some  STWAVE 
model  options  are  unique  to  either  half-plane  or  full-plane  mode.  Table  1 
summarizes  these  features.  Previously  mentioned  features  that  are  not 
listed  in  this  table  are  available  in  both  modes. 


Table  1.  Summary  of  half-plane  and  full-plane  features. 


Feature 

HP 

FP 

Wave  transformation  and  generation  on  full  360-deg  plane 

X 

Option  for  wave-current  interaction 

X 

Option  for  direct  input  of  wave  parameters  to  create  TMA  spectrum 

X 

Direction  bins  restricted  to  5  deg 

X 

DX  and  DY  grid  cell  spacing  must  be  the  same 

X 

Requires  iterative  criteria 

X 

Additionally,  both  the  half-plane  and  full-plane  modes  of  STWAVE  can  be 
executed  in  serial,  and  parallel  in  time  or  space.  Serial  execution  utilizes  one 
processor,  allowing  STWAVE  to  run  on  a  personal  computer.  Parallel  in 
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time  indicates  time  decomposition.  Time  decomposition  is  essentially  serial 
execution  with  multiple  processors  whereby  each  wave  instance,  referred  to 
as  a  wave  snap  and  identified  by  a  snap  identification  (snap  IDD),  is 
completed  using  its  own  processor  (e.g.,  93  wave  instances  could  use 
93  processors).  The  parallel  in  space  execution  uses  domain  decomposition 
where  the  computational  grid  is  broken  into  different  sections  with  each 
section  residing  on  a  different  computer  processor.  This  allows  for  larger 
modeling  domains  and  finer  resolution.  An  example  schematic  of  the 
domain  decomposition  for  half-plane  and  full-plane  grids  is  shown  below  in 
Figure  1.  While  a  full-plane  grid  can  be  separated  in  both  the  I-  and  J- 
directions,  a  half-plane  grid  can  only  be  segmented  in  the  J-direction  (with  I 
being  the  primary  wave  propagation  direction).  The  domain  decomposition 
does  not  require  any  pre-processing  and  is  performed  automatically  when 
the  model  begins  execution.  Additional  information  regarding  grid 
orientation  is  provided  in  the  Numerical  Discretization  section. 


Figure  1.  Example  full-plane  and  half-plane  domain  decompositions  for  parallel 

applications. 


The  parallelized  in  space  STWAVE  can  be  coupled  to  ADCIRC  (Advanced 
CIRCulation  model  for  shelves,  coasts,  and  estuaries)  using  the  ERDC 
Coastal  Storm  Modeling  (CSTORM-MS)  coupler  that  takes  advantage  of 
and  is  compatible  with  the  Earth  System  Modeling  Framework  (ESMF) 
software.  This  circulation-wave  coupling  allows  the  two  models  to  run 
sequentially  providing  feedback  responses  (leap-frogging  through  time)  to 
each  other  by  sharing  information  via  memory  and  processors. 
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Model  assumptions 

The  assumptions  made  in  STWAVE  version  6.0  are  the  following: 

1.  Phase-averaged.  STWAVE  is  based  on  the  assumption  that  relative  phases 
of  the  spectral  components  are  random,  and  phase  information  is  not 
tracked.  In  order  to  resolve  detailed  near-field  reflection  and  diffraction 
patterns  near  coastal  structures,  a  phase-resolving  model  should  be 
applied. 

2.  Mild  bottom  slope  and  negligible  wave  reflection.  Waves  reflected  from 
the  shoreline  or  from  steep  bottom  features  are  neglected. 

3.  Steady-state  waves,  currents,  and  winds.  STWAVE  is  formulated  as  a 
steady-state  model,  which  reduces  computation  time  and  is  appropriate 
for  wave  conditions  that  vary  more  slowly  than  the  time  it  takes  for  waves 
to  transit  the  domain.  For  wave  generation,  the  steady-state  assumption 
means  that  the  winds  have  remained  steady  sufficiently  long  for  the  waves 
to  attain  fetch-limited  or  full-developed  conditions  (waves  are  not  limited 
by  the  duration  of  the  winds). 

4.  Linear  reflection  and  shoaling.  STWAVE  incorporates  linear  wave 
refraction,  shoaling,  and  propagation,  and  thus,  does  not  represent  wave 
asymmetry  or  other  nonlinear  wave  features.  Model  accuracy  is  reduced 
(e.g.,  underestimated  wave  heights)  at  large  Ursell  numbers. 

5.  Depth-uniform  current.  The  wave-current  interaction  in  the  model  is 
based  on  a  current  that  is  constant  throughout  the  water  column;  the 
modification  of  refraction  and  shoaling  due  to  strong  vertical  gradients  is 
not  represented. 

6.  Linear  radiation  stress.  Radiation  stress  is  calculated  based  on  linear  wave 
theory. 
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3  Governing  Equations  and  Numerical 
Discretization 

Governing  equations 

STWAVE  simulates  depth-induced  wave  refraction  and  shoaling,  current- 
induced  refraction  and  shoaling,  depth-and  steepness-induced  wave 
breaking,  wind-wave  growth,  and  wave-wave  interaction  and  whitecapping 
that  redistribute  and  dissipate  energy  in  a  growing  wave  field. 

The  governing  equations  are  similar  between  the  half-plane  and  full-plane 
modes.  Governing  equations  for  half-plane  mode  will  be  discussed  first 
since  this  option  includes  the  interaction  of  waves  with  currents  by 
considering  a  reference  frame  moving  with  the  current.  Wave  parameters  in 
this  frame  are  denoted  with  the  subscript  r  as  being  “relative”  to  the  current 
and  parameters  in  the  nonmoving  reference  frame  are  denoted  with  the 
subscript  a  for  “absolute.” 

The  wave  dispersion  relation  is  given  in  the  moving  reference  frame  as 
(Jonsson  1990  and  others): 

go*  =  gktanh^kd),  (l) 


where: 

a)  =  angular  frequency, 
g  =  gravitational  acceleration, 
k  =  wave  number, 
d  =  water  depth. 

In  the  absolute  frame  of  reference,  the  dispersion  equation  is: 

coa  =  cor  +kUccos(8-a),  (2) 


where: 


Uc  =  current  speed, 
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8  =  direction  of  the  current  relative  to  a  reference  frame  (x-axis), 
a  =  wave  orthogonal  direction  (normal  to  wave  crest). 

The  wave  number  is  solved  by  substituting  Equation  l  into  Equation  2  and 
iteratively  solving  for  k.  The  wave  number  and  wavelength  (L  =  2.71 /k)  are 
the  same  in  both  reference  frames. 

Wave  celerity,  C,  and  group  celerity,  Cg,  are  required  to  calculate  shoaling 
and  refraction  solutions  in  both  frames.  In  the  reference  frame  relative  to 
the  current, 


C. 


(3) 


C 


gr 


0.5  C. 


1+ 


2kd 

sinh(2  kd)/ 


(4) 


The  direction  of  the  relative  group  celerity  is  a,  the  wave  orthogonal 
direction,  see  Figure  2.  In  the  absolute  reference  frame, 

C„=C,+C7ccos(S— a),  (5) 

<6> 

where  i  is  tensor  notation  for  the  x-  and  y-components.  The  direction  of 
the  wave  ray  is  defined  as: 


k 


tan 


Cnr  sin  a  +  £7  sin  5 
C  cos  a  +  £7  cos  8 

y>  L  / 


(7) 


The  distinction  between  the  wave  orthogonal  (direction  perpendicular  to 
the  wave  crests)  and  the  wave  ray  (direction  of  energy  propagation)  is 
important  in  describing  wave-current  interaction.  Without  currents,  as  in 
the  full-plane  mode,  the  wave  rays  and  wave  orthogonals  are  the  same,  but 
with  currents,  the  wave  energy  moves  along  the  wave  rays  whereas  the 
wave  direction  is  defined  by  the  wave  orthogonals.  A  definition  sketch  of 
wave  and  current  vectors  is  provided  in  Figure  2. 
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Figure  2.  Definition  sketch  of  wave  and  current  vectors,  from  Smith 

et  al.  2001. 


The  wave  orthogonal  direction  for  steady-state  conditions  in  the  presence 
of  currents  is  given  by  (Mei  1989;  Jonsson  1990): 


,  Da  _  Crk  Dd  kt  DUci 
ga  DR  sinh(2/cd)  Dna  k  Dn0 


When  wave-current  interactions  are  excluded,  the  wave  orthogonal 
direction  for  steady-state  conditions  is  given  by: 


,  Da  _  Ck  Dd 
9  DR  sinh(2fai)  Dno  ’ 


(9) 


where: 

D  =  total  derivative, 

R  =  coordinate  in  the  direction  of  the  wave  ray, 
n0  =  coordinate  normal  to  the  wave  orthogonal. 

The  governing  equation  for  steady-state  conservation  of  spectral  wave 
action  along  a  wave  ray  accounting  for  wave-current  interaction  is 
(Jonsson  1990), 
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c  ]  d  CaCgaCQs(n-a)E(<Da,a)  _  s 

dx :  ft)  ^  Cl) 


ga 


(10) 


with  a  similar  version  for  no  wave-current  interaction  (full-plane  mode  or 
zero  current  in  half-plane  mode), 


,  \  d  CCgcos(a)E(co,a) 

'  9'idxi  co 


(11) 


where: 

E  =  wave  energy  density  divided  by  both  pw  and  g  where  pw  is  the 
density  of  water, 

S  =  energy  source  and  sink  terms. 

Refraction  and  shoaling 

Refraction  and  shoaling  are  implemented  in  STWAVE  by  applying  the 
conservation  of  wave  action  along  backward  traced  wave  rays.  Wave  rays 
are  traced  in  a  piecewise  manner,  from  the  previous  grid  column  or  row. 

The  two-dimensional  (2-D)  wave  spectra  are  set  as  input  along  the  first  grid 
column  (the  offshore  boundary)  in  half-plane  mode  or  along  all  grid 
boundaries  in  full-plane  mode.  The  spectrum  is  calculated  by  back  tracing  a 
wave  ray  for  each  frequency  and  direction  component  of  the  spectrum.  The 
wave  ray  direction,  p,  is  determined  by  Equation  7  for  a  half-plane 
simulation  with  wave-current  interaction,  and  only  wave  ray  directions 
propagating  toward  the  shore  (-87.5  to  +87.5  deg)  are  included.  As 
previously  mentioned,  energy  propagating  toward  the  offshore  is  neglected 
in  half-plane  mode.  For  a  full-plane  simulation,  the  wave  ray  direction  is  the 
same  as  the  wave  orthogonal  as  wave-current  interactions  are  neglected. 

The  wave  ray  is  traced  back  to  the  previous  grid  column  or  row  (whichever 
is  encountered  first),  and  the  length  of  the  wave  ray  segment  DR  is 
calculated.  Derivatives  of  depth  and  current  components  (if  applicable) 
normal  to  the  wave  orthogonal  are  estimated  (based  on  the  orthogonal 
direction)  and  substituted  into  Equation  8  for  half-plane  or  Equation  9  for 
full-plane  to  calculate  the  wave  orthogonal  direction  at  the  previous  column. 
The  wavenumber,  wave  and  group  celerities,  and  wave  ray  angle  in  the 
previous  column  or  row  are  then  calculated. 
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The  energy  is  calculated  as  a  weighted  average  of  energy  between  two 
adjacent  grid  points  in  the  column  and  direction  bins.  The  energy  density  is 
corrected  by  a  factor  of  the  ratio  of  the  standard  angle  band  width  (5-deg  for 
the  half-plane  and  user-specified  in  the  full-plane)  to  the  width  of  the  back- 
traced  band  to  account  for  the  distortion  of  the  bins  through  refraction.  The 
shoaled  and  refracted  wave  energy  is  then  calculated  from  the  conservation 
of  wave  action  along  a  ray  using  Equation  10  and  11  for  half- plane  and  full- 
plane,  respectively. 

Source  and  sink  terms 

Surf-zone  wave  breaking 

The  wave-breaking  criterion  applied  in  STWAVE  is  a  function  of  wave¬ 
length  and  water  depth: 


Hm°nm  =  O.lLtanh(kd), 


(12) 


where: 

Hmo.max  =  maximum  energy-based  zero-moment  wave  height, 

L  =  wavelength. 

This  criterion  is  powerful  because  it  includes  both  the  impacts  of  depth-  and 
steepness-limited  breaking.  At  a  coastal  entrance,  where  waves  steepen 
because  of  the  wave-current  interaction,  wave  breaking  is  enhanced  because 
of  the  increased  wave  steepness.  Laboratory  experiments  conducted  by 
Smith  et  al.  (1997)  of  irregular  wave  breaking  on  ebb  currents  found  that  a 
breaking  relationship  in  the  form  of  the  Miche  criterion  (1951)  was  simple, 
robust,  and  accurate  (see  also  Battjes  1982  and  Battjes  and  Janssen  1978). 
Equation  12  is  applied  in  STWAVE  as  the  maximum  limit  on  the  zero- 
moment  wave  height.  The  energy  in  the  spectrum  is  reduced  at  each 
frequency  and  direction  in  proportion  to  the  amount  of  pre-breaking  energy 
in  each  frequency  and  direction  band.  Nonlinear  transfers  of  energy  to  high 
frequencies  that  occur  during  breaking  are  not  represented  in  the  model. 
Model  grid  cells  where  the  wave  is  limited  by  Equations  12  are  flagged  as 
actively  breaking  cells. 
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Wind  Input 

Waves  grow  through  the  transfer  of  momentum  from  the  wind  field  to  the 
wave  field.  The  flux  of  energy,  Fin,  into  the  wave  field  is  implemented  into 
STWAVE  by  the  following  equation  (Resio  1988): 

^*fn  =  0.85A— Cm  — ,  (13) 

Pw  9 


where: 

A  =  partitioning  coefficient  that  represents  the  percentage  of  total 
atmosphere  to  water  momentum  transfer  that  goes  directly  to 
the  wave  field  (a  value  of  0.75  is  typical), 
pa  =  density  of  air, 
pw  =  density  of  water, 

Cm  =  mean  wave  celerity, 

u*  =  frictional  velocity  (equal  to  the  product  of  the  wind  speed  Umag 
and  the  square  root  of  the  drag  coefficient  Cd  = 

0. 0012+0. 000025Umag). 

In  deep  water,  STWAVE  provides  a  total  energy  growth  rate  that  is 
consistent  with  that  reported  in  Hasselmann  et  al.  (1973). 


The  energy  gain  to  the  spectrum  is  calculated  by  multiplying  the  energy 
flux  by  the  equivalent  time  for  the  wave  to  travel  across  a  grid  cell, 


At 


Ax 

PC  g  cos  (amy 


(14) 


where: 

At  =  equivalent  travel  time, 

Ax  =  grid  spacing, 

/ 3  =  factor  equal  to  0.9  for  wind  seas, 

C  g  =  average  group  celerity  of  the  spectrum, 

am  =  mean  wave  direction  relative  to  the  grid. 
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For  half-plane  mode,  only  winds  blowing  towards  the  shore  (+x-direction) 
are  included,  and  wave  damping  by  offshore  winds  and  growth  of  offshore- 
traveling  waves  are  neglected. 

Wave-wave  interaction  and  whitecapping 

As  energy  is  fed  into  the  waves  from  the  wind,  it  is  redistributed  through 
nonlinear  wave-wave  interactions.  Energy  is  transferred  from  the  peak  of 
the  spectrum  to  both  lower  frequencies  (decreasing  the  peak  frequency  or 
increasing  the  peak  period)  and  to  higher  frequencies  (where  it  is 
dissipated). 

In  STWAVE,  the  frequency  of  the  spectral  peak  is  allowed  to  increase  with 
fetch  (or,  equivalently,  propagation  time  across  a  fetch).  The  equation  for 
this  rate  of  change  of  /),  integrated  over  a  single  time-step,  At,  is  given  by 
Equation  15, 


[  _  /  > 

4/3 

IL 

At 

v  ph  5 

{9} 

-3/7 


(15) 


where  th ej  andj+i  subscripts  refer  to  the  grid  column  indices  within 
STWAVE  and  ^is  a  dimensionless  constant  (Resio  and  Perrie  1989).  The 
energy  gained  by  the  spectrum  is  distributed  amongst  frequencies  lower 
than  the  peak  frequency  in  a  manner  that  retains  the  self-similar  shape  of 
the  spectrum. 

Wave  energy  is  dissipated  through  energy  transferred  to  high  frequencies, 
wave  breaking  (whitecapping),  and  turbulent/ viscous  effects.  This 
dissipation  occurs  most  notably  in  an  actively  growing  wave  field.  There  is  a 
dynamic  balance  between  energy  entering  the  wave  field  due  to  wind  input 
and  energy  leaving  the  wave  field  because  of  nonlinear  fluxes  to  higher 
frequencies  (Resio  1987;  Resio  1988).  The  energy  flux  to  higher  frequencies 
is  represented  in  STWAVE  as: 


tanh3/4  (kpd)  ’ 


where: 
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Je  =  energy  flux, 
e  =  coefficient  equal  to  30, 

Etot  =  total  energy  in  the  spectrum  divided  by  pw  and  g, 
kp  =  wave  number  associated  with  peak  of  the  spectrum. 

The  energy  loss  from  the  spectrum  is  calculated  by  multiplying  the  energy 
flux  by  the  equivalent  time  for  the  wave  to  travel  across  a  grid  cell  (Equa¬ 
tion  14)  with  /3  =  1.0  for  the  swell  portion  of  the  spectrum  and  0.9  for  the  sea 
portion  of  the  spectrum.  This  dissipation  is  only  applied  in  STWAVE  if  wind 
input  is  included. 


Bottom  friction 

STWAVE  includes  two  formulations  for  bottom  friction.  The  first  is  the 
JONSWAP  formulation  (Hasselmann  et  al.  1973;  Padilla-Hernandez  2001), 
where  the  spectral  energy  loss  due  to  bottom  friction  is  formulated  as, 


O 


sinh2  (kd) 


E(f,a). 


(17) 


where: 


/  =  wave  frequency. 

The  value  of  the  friction  coefficient  c/  can  be  set  as  a  constant  over  the 
domain  or  specified  individually  for  each  STWAVE  cell.  For  the  JONSWAP 
bottom  friction  formulation,  c/is  specified  as  E/g,  where  the  recommended 
values  of  r for  sand  beds  are  in  the  range  of  0.038  to  0.067  m2/ss  (or  c/= 
0.004  to  0.007)  based  on  experiments  in  the  North  Sea.  Equation  17  has  a 
weak  inverse  dependence  on  water  depth  as  a  result  of  the  increase  in 
bottom  wave  orbital  velocity  as  the  relative  depth,  kd,  decreases. 


A  Manning’s  n  formulation  is  also  available  in  STWAVE  (Holthuijsen  2007), 


1 

9 


gn 


d1/3 


a 


sinh2  (kd) 


E(f,a)u 


rms  > 


(18) 


where  the  value  of  n  is  specified  as  input  to  STWAVE  (either  spatially 
constant  or  variable)  and  Urms  is  the  root-mean-square  bottom  velocity. 
With  the  Manning’s  formulation,  bottom  friction  dissipation  has  an 
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additional  inverse  dependence  on  water  depth.  Estimates  of  Manning’s  n 
coefficients  are  available  in  most  fluid  mechanics  reference  books  (e.g., 
o.oi  to  0.05  for  smooth  to  rocky /weedy  channels). 

Bottom  friction  in  STWAVE  has  been  used  to  represent  dissipation  over 
coral  reefs  in  Hawaii  and  wetlands  in  southern  Louisiana. 


Radiation  stress  gradients 


Gradients  in  radiation  stress  are  calculated  in  STWAVE  to  provide  wave 
forcing  to  external  circulation  models,  such  as  ADCIRC,  to  drive  nearshore 
currents  and  water  level  changes  (i.e.,  wave  setup  and  setdown).  Wave- 
driven  currents  are  generally  the  dominant  forcing  for  sediment  transport 
in  the  surf-zone.  Radiation  stress  tensors  are  calculated  based  on  linear 
wave  theory: 


S**  =pwg$E(f,a 


0.5 


2  kd 


sinh(2kd) 


cos2a  +  l)-0.5 


dfda,  (19) 


E{f,a) 


0.5 


2  kd 


sinh(2kd) 


sin  2a 


dfda, 


(20) 


Syy  =pw9$E{f,a 


0.5 


2  kd 


sinh(2kd) 


sin  a +  1-0.5 


dfda.  (21) 


The  gradients  in  radiation  stress  are  calculated  as  follows: 


9S„ 

9SV 

dx 

dy 

.  dS*y 

^yy 

dx 

dy 

(22) 

(23) 


Values  of  t x/pw  and  ry/pw  can  be  output  from  STWAVE  for  use  in 
circulation  modeling. 

Numerical  discretization 

STWAVE  is  a  finite-difference  numerical  model,  formulated  on  a  Cartesian 
grid.  Grid  cells  are  required  to  be  square  (DX  =  DY)  for  half-plane 
simulations,  but  DX  and  DY  do  not  need  to  be  the  same  for  full-plane 
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simulations.  STWAVE  operates  in  a  local  coordinate  system,  with  the  x-axis 
oriented  in  the  cross-shore  direction  and  the  y-axis  oriented  alongshore, 
forming  a  right-handed  coordinate  system.  A  schematic  of  the  grid 
orientation  is  provided  in  Figure  3.  Typically,  the  y-axis  is  aligned  with  the 
bottom  contours  so  the  offshore  boundary  is  parallel  with  the  shoreline. 
Wave  angles  are  defined  in  a  mathematical  sense,  measured  counter¬ 
clockwise  from  the  x-axis.  Lateral  boundaries  in  the  model  can  be  specified 
as  land  or  water  by  specifying  the  cell  depth  as  positive  (water)  or  negative 
(land).  While  land  boundaries  will  reduce  wave  growth  near  the  boundaries 
as  they  “prevent”  propagation  from  landward  directions,  water-defined 
boundaries  allow  a  zero-gradient  type  of  boundary  condition.  This  zero- 
gradient  boundary  condition  allows  energy  consistent  with  that  of 
neighboring  cells  to  propagate  into  or  out  of  the  domain  along  the  lateral 
boundary. 


Figure  3.  A  schematic  of  a  STWAVE  grid. 


Units 


STWAVE  is  formulated  in  metric  units.  Water  heights,  water  depth,  and 
tide/surge  elevation  adjustments  are  in  meters,  winds  are  in  meters/second, 
wave  periods  are  in  seconds,  and  energy  densities  are  in  m2/Hz/radian. 
Wave  and  wind  directions  are  input  and  output  in  units  of  degrees  which 
are  measured  counterclockwise  from  the  grid  x-axis,  but  are  converted  to 
radians  for  model  computations. 
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4  STWAVE  Files 

The  primary  input  file  required  for  a  STWAVE  simulation  is  the  simulation 
file  (*.sim).  It  is  within  this  file  that  the  model  controls  and  input/output 
options  are  defined.  Optional  input  files  include  bathymetry  (DEP),  spatially 
varying  surge  or  tidal  water  level  adjustments  (SURGE),  incident  wave 
spectra  (SPEC),  spatially  varying  wind  (WIND),  spatially  varying  friction 
coefficients  (FRIC),  and  current  fields  (CURR). 

Depending  on  which  options  are  selected  in  the  *.sim  file,  STWAVE  may 
generate  two  to  eight  output  files.  The  primary  output  files  for  STWAVE 
are  the  wave  field  (WAVE)  and  peak  wave  period  (TP)  files.  The  wave  field 
file  contains  the  zero-moment  wave  height  Hmo  in  meters,  the  peak  period 
Tp  in  seconds,  and  the  mean  wave  direction  relative  to  the  STWAVE  grid 
am  in  degrees  for  all  grid  cells  for  all  snap  IDD’s,  e.g.,  individual  wave 
instances.  Additional  output  files  are  wave  spectra  at  selected  grid 
locations  (OBSE),  wave  breaking  indices  and  dissipation  (BREAK), 
radiation  stress  gradients  (RADS),  wave  parameters  at  selected  grid 
locations  (SELH),  wave  information  at  interpolated  station  locations 
(STATION),  and  nesting  spectra  (NEST).  Figure  4  shows  a  diagram  of 
input  and  output  files  used  in  a  STWAVE  simulation  with  additional  file 
information  provided  in  Table  2. 


Figure  4.  STWAVE  input  and  output  files. 
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Table  2.  STWAVE  simulation  files. 


Variable 

Example  filename 

Input/output 

Type 

Description 

SIM 

projname.  sim 

Input  -  required 

Simulation  file 

Model  parameters 

DEP 

projname.dep 

Input -optional 

Global  spatial  data  set 

Non-time-dependent 

Bathymetry  values  (m)  for  each  grid  cell 

Water  depths  are  defined  as  positive  numbers  and 
land  elevations  as  negative  numbers 

SURGE 

proj name. surge,  in 

Input -optional 

Global  spatial  data  set 

Time-dependent 

Water  level  adjustment  (m)  for  each  grid  cell 
relative  to  bathymetry  datum 

Positive  values  increase  water  depth  and  negative 
values  decrease  water  depth 

Must  be  specified  for  every  snap  IDD 

SPEC 

projname.e  ng 

Input -optional 

Spectral  file 

Incident  2-D  wave  energy  spectra  (m2/Hz/rad) 

Must  be  specified  for  every  snap  IDD 

WIND 

projname.  wind. in 

Input -optional 

Global  spatial  data  set 

Time-dependent 

Wind  speed  (m/s)  and  direction  (deg)  for  each  grid 

cell 

Wind  direction  is  considered  relative  to  the  STWAVE 

coordinate  system  and  is  measured 
counterclockwise  from  the  x-axis  (same  convention 
used  for  wave  direction) 

Must  be  specified  for  every  snap  IDD 

FRIC 

projname.  fric.dat 

Input -optional 

Global  spatial  data  set 

Non-time-dependent 

Friction  coefficient  (Cf  or  n)  for  each  grid  cell 

CURR 

projanme.  curr.in 

Input -optional 

Global  spatial  data  set 

Time-dependent 

Current  vector  specified  as  x-  and  y-  components 
for  each  grid  cell  (u,v  pair  in  m/s) 

One  current  field  can  be  used  for  all  model  runs  or 

one  may  be  specified  for  every  snap  IDD 

WAVE 

projname.wave.out 

Output  -  required 

Global  spatial  data  set 

Time-dependent 

Wave  height  in  meters  (Hmo),  peak  period  in 
seconds  (Tp),  and  mean  wave  direction  relative  to 
the  STWAVE  grid  in  degrees  (a,„)  for  each  grid  cell 

TP 

projname.  tp.out 

Output  -  required 

Global  spatial  data  set 

Time-dependent 

Peak  wave  period  (s)  for  each  grid  cell 

OBSE 

projname.obse.out 

Output  -  optional 

Spectral  file 

Transformed  energy  spectra  at  selected  (l,J)  grid 
cell  locations  (m2/Flz/rad) 

BREAK 

projname.brk 

Output  -  optional 

Global  spatial  data  set 

Time-dependent 

Wave  breaking  indices  or  dissipation  (m2/s)  for 

each  cell 

Index  of  1  for  actively  breaking  cells  and  index  of  0 
for  nonbreaking  cells 

RADS 

projname.  rads.out 

Output  -  optional 

Global  spatial  data  set 

Time-dependent 

Radiation  stress  gradients  (m2/s2)  for  each  cell. 

Used  by  circulation  models  to  force  wave-driven 
currents  and  water  level  changes.  Stress  in  these 
units  is  obtained  by  dividing  stress  in  units  of  N/m2 
by  the  reference  density  of  water  (1,000  kg/m3). 

SELH 

prq/'name.selh.out 

Output  -  optional 

Local  spatial  data  set 

Hmo,  Tp,  and  a,„  for  selected  (l,J)  grid  cell  locations 

STATION 

pro/name.stat.out 

Output  -  optional 

Local  spatial  data  set 

Hmo,Tp,  and  a„,at  interpolated  (x,y)  coordinate  points 

NEST 

pro/'name.nest.out 

Output  -  optional 

Spectral  file 

Transformed  energy  spectra  saved  at  selected  (l,J) 
grid  cell  locations  for  nesting  application 
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5  Model  Controls 

Model  parameters 

The  simulation  file  (*.sim)  specifies  options  for  running  STWAVE  and 
identifies  special  output  points  as  well  as  spatially  constant  input  para¬ 
meters  like  friction.  The  simulation  file  is  a  simple  text  ASCII  file  that  is 
separated  into  a  series  of  FORTRAN  namelists.  Depending  on  the  model 
controls  provided  in  the  *.sim  file,  some  of  these  namelists  are  required 
while  others  are  optional.  The  namelist  are  required  to  appear  in  a  certain 
order  in  relation  to  each  other.  The  order  of  all  possible  namelist  is  given  in 
Table  3  along  with  a  brief  description  of  each.  The  start  of  a  namelist  is 
signified  by  using  the  ampersand  symbol  “&”  followed  by  the  namelist’s 
name.  Then  the  variables  assigned  to  that  namelist  are  listed  along  with  an 
assigned  value.  The  end  of  the  namelist  is  signified  with  the  slash  symbol 
“/”.  Comments  to  enhance  user  readability  can  be  inserted  between 
namelist  by  using  pound  symbols  “#”  in  column  1  of  the  *.sim  file  with  the 
comment  followed  on  the  same  line.  STWAVE  *.sim  files  used  in  conjunct- 
tion  with  SMS  (Surfacewater  Modeling  System)  version  11.0+  must  have  the 
following  text  on  line  1:  “#  STWAVE_SIM_FILE”,  without  the  quotes.  The 
SMS  system  will  automatically  format  an  STWAVE  *.sim  file  in  the  correct 
manner  for  the  user  through  a  series  of  GUI  controls  related  to  STWAVE. 

Descriptions  of  the  standard  model  inputs,  which  are  defined  in  the 
std_parms  namelist,  are  provided  here  and  include  the  following: 

IPLANE  =  Switch  to  run  either  the  half-plane  (IPLANE  =  o)  or  full-plane 
(IPLANE  =  1)  mode  of  STWAVE. 

IPRP  =  Switch  for  including  propagation  only  (IPRP  =  1)  or  both 

propagation  and  source  terms  (IPRP  =  o).  Surf-zone  wave  breaking 
is  included  for  both  options,  but  wind-wave  generation,  wave-wave 
interactions,  and  whitecapping  are  included  only  for  IPRP  =  o. 
Propagation  only  is  usually  sufficient  for  shorter  wave  propagation 
distances  (on  the  order  of  kilometers).  Source  terms  should  be 
included  for  longer  wave  propagation  distances  or  cases  where  only 
locally  generated  waves  exist. 
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Table  3.  Ordered  listing  of  all  STWAVE  *.sim  file  FORTRAN  namelists. 


Order 

STWAVE  Namelist 

Description 

1 

std_parms 

Standard  model  controls 

2 

run_parms 

Runtime  parameters,  ex.  number  of  snaps 

3 

spatial_grid_parms 

Parameters  related  to  the  computational  spatial  grid 

4 

input_files 

Names  and  types  of  input  files 

5 

output_files 

Names  and  types  of  output  files 

6 

time_parms 

Time  variables  (Optional) 

7 

const_spec 

Constant  boundary  input  spectrum  information  (Optional) 

8 

depth_func 

Analytic  depth  function  (Optional) 

9 

const_fric 

Spatially/temporally  constant  friction  value  (Optional) 

10 

snapjdds 

Labels  for  each  snap  (Optional) 

11 

select_pts 

List  of  special  output  (l,J)  grid  locations  (Optional) 

12 

nest_pts 

List  of  output  (l,J)  grid  points  for  nesting  (Optional) 

13 

stationjocations 

List  of  special  output  (x,y)  location  coordinates  (Optional) 

14 

const_wind 

Spatially  constant  but  time  varying  winds  (Optional) 

15 

const_surge 

Spatially  constant  but  time  varying  surge  levels  (Optional) 

16 

const_tma_spec 

Spatially  constant  but  time  varying  TMA  spectrum  values  (Optional) 

ICUR  =  Switch  for  including  (ICUR  =  l  or  2)  or  excluding  (ICUR  =  o) 
wave-current  interaction.  Currently,  wave-current  interaction  is 
only  available  for  half-plane  simulations.  A  current  field  must  be 
specified  for  each  snap  IDD  if  ICUR  =  1.  ICUR  =  2  specifies  a  single 
current  field  for  all  snap  IDD’s,  and  is  useful  for  climatic  studies 
where  peak  ebb  or  flood  current  fields  are  used  in  conjunction  with 
multiple  typical  or  extreme  incident  wave  conditions. 

IBREAK  =  Switch  for  identifying  (IBREAK  =  1  or  2)  or  not  identifying 

(IBREAK  =  o)  actively  breaking  wave  cells.  Cells  in  which  the  waves 
are  actively  dissipating  wave  energy  are  identified  by  binary  indices 
if  IBREAK  =  1  while  IBREAK  =  2  prints  out  the  dissipation.  The 
value  of  IBREAK  simply  determines  if  an  output  file  is  written  to 
indicate  which  cells  are  breaking  and  has  no  impact  on  the 
simulated  wave  fields  or  the  breaking  calculation. 


IRS  =  Switch  for  calculating  (IRS  =  1)  or  not  calculating  (IRS  =  o) 

radiation  stress  gradients.  The  radiation  stress  gradients  are  not 
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used  by  STWAVE,  but  can  be  used  as  input  for  circulation  models 
(ex.,  ADCIRC)  to  force  wave-drive  currents  and  water  levels. 

NSELCT  =  Number  of  optional  (I,  J)  grid  cell  output  points.  The  2-D 

transformed  wave  spectra  are  saved  to  the  OBSE  file  while  wave 
height,  period,  and  direction  are  written  to  the  SELH  file  for  these 
selected  points.  Wave  height,  period,  and  direction  are  saved  to  all 
grids  points  in  the  WAVE  file,  but  this  summary  file  is  useful  to 
check  results  at  critical  locations,  compare  results  with 
measurement,  or  to  isolate  locations  of  interest. 

NNEST  =  Number  of  optional  (I,  J)  grid  cell  output  points  to  save  spectra 
for  nesting  applications.  Grid  nesting  is  used  to  decrease 
computational  time  whereby  a  coarse  offshore  grid  is  used  to  drive 
multiple  nearshore  simulations.  Wave  spectra  from  the  coarse  grid 
are  saved  at  select  points  that  coincide  with  the  offshore  boundary 
of  the  nearshore  grid.  Then  a  separate  STWAVE  model  is  initiated 
to  interpolate  the  coarse  grid  spectra  onto  the  nearshore  grid  and 
model  the  nearshore  wave  transformations.  Further  information  on 
grid  nesting  is  provided  by  Smith  and  Smith  (2002). 

NSTATIONS  =  Number  of  optional  (x,y)  interpolated  output  points.  These 
interpolated  points  are  defined  using  x-  and  y-coordinates  of  the 
same  coordinate  system  as  the  grid  origin  and  orientation,  not  (I,J) 
grid  cell  locations.  Wave  height,  period,  and  direction  for  these 
points  are  written  to  the  STATION  file.  Currently,  the 
NSTATIONS  option  is  only  a  place  holder  and  will  be 
functional  in  future  STWAVE  versions. 

IBND  =  Switch  for  single  point  entry  (IBND  =  o),  linear  interpolation 
(IBND  =  1),  or  morphic  interpolation  (IBND  =  2)  of  spectra  on 
boundaries.  IBND  =  o  indicates  that  a  single  input  spectrum  is 
applied  along  the  entire  grid  boundary  and,  thus,  should  be 
established  along  an  offshore  depth  contour  where  the  wave 
spectrum  is  fairly  homogenous  (no  large  shoals  or  canyons  offshore 
of  the  boundary).  IBND  =  1  or  2  is  used  anytime  multiple  input 
spectra  are  applied  along  the  grid  boundary,  as  is  usually  the  case 
with  nesting  from  a  coarser  or  larger  domain  model  to  a  finer 
resolved  grid. 
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For  IBND  =  1,  the  interpolation  method  is  linear.  The  energy 
density  for  each  wave  spectrum  frequency-direction  bin  is  bi- 
linearly  interpolated  from  the  same  bins  of  the  adjacent  spectra.  If 
points  along  the  boundary  are  sufficiently  dense  to  define  the 
variation  in  spectra,  linear  interpolation  gives  good  results. 

For  IBND  =  2,  the  interpolation  method  is  morphic.  Morphic 
interpolation  was  developed  to  preserve  the  shape  of  the  direction 
distribution  when  spectra  are  widely  spaced  (wave  directions  vary 
by  10-15+  deg  from  grid  point  to  grid  point)  or  bathymetry  is 
complex.  The  morphic  technique  is  applicable  only  for  single 
peaked  wave  spectra,  and  is  appropriate  for  climatic  wave 
transformation  studies  where  a  parametric  spectral  shape  is  applied 
based  on  wave  parameters.  Further  information  regarding  these 
interpolation  techniques  can  be  found  in  Smith  and  Smith  (2002). 

IFRIC  =  Switch  for  including  (IFRIC  =  1,  2,  3,  and  4)  or  excluding  (IFRIC 
=  o)  bottom  friction.  Two  formulations  are  included  in  STWAVE,  a 
JONSWAP  (IFRIC  =  1  or  2)  and  Manning  formulation  (IFRIC  =  3  or 
4).  For  the  JONSWAP  formulation,  c/ is  specified.  For  the  Manning 
formulation,  Manning’s  n  is  the  input  value.  Spatially  constant 
friction  (IFRIC  =  1  or  3)  requires  the  simulation  file  to  contain  a 
single  value  of  the  friction  coefficient  while  spatially  variable 
friction  (IFRIC  =  2  or  4)  requires  an  input  file,  FRIC,  that  specifies 
the  friction  coefficient  for  every  grid  cell.  The  preferred  method  of 
specifying  c/  or  n  is  through  calibration  with  measurements. 

ISURGE  =  Switch  for  spatially  constant  (ISURGE  =  o)  or  spatially  variable 
(ISURGE  =  1)  water  level  correction  over  the  grid.  This  depth 
correction  over  the  grid  is  used  primarily  to  account  for  tidal  offsets 
or  storm  surges.  A  surge  file  (SURGE)  specifying  the  adjustment  for 
every  grid  cell  is  required  only  if  ISURGE  =  1.  For  ISURGE  =  o,  the 
water  level  correction  is  specified  in  the  simulation  file. 

IWIND  =  Switch  for  spatially  constant  (IWIND  =  o)  or  spatially  variable 

(IWIND  =  1)  wind  over  the  grid.  The  WIND  file  specifying  the  wind 
speed  and  direction  for  each  grid  cell  is  required  only  if  IWIND  =  1; 
for  IWIND  =  o,  the  wind  speed  and  direction  are  defined  in  the 
simulation  file.  The  wind  enters  into  the  model  simulations  only  if 
IPRP  =0. 
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IDEP_OPT  =  Switch  for  depth  to  be  provided  by  a  bathymetry  file 
(IDEP_OPT  =  o)  or  to  be  defined  as  a  plane  sloping  bottom 
(IDEP_OPT  =  l).  The  DEP  file  is  required  only  if  IDEP_OPT  =  o 
and  specifies  the  bathymetry  for  each  grid  cell;  otherwise,  for 
IDEP_OPT  =  l,  offshore  water  depth  and  constant  bed  slope  are 
specified  in  the  simulation  file. 

I_BC(ISIDE)  =  Switch  for  boundary  condition  defined  as  a  zero  spectrum 
(I_BC  =  o),  constant  TMA  spectrum  (I_BC  =1),  constant  spectrum 
read  from  an  ENG  file  (I_BC  =  2),  or  l-D  transformed  spectrum 
(I_BC  =  3).  One  of  these  boundary  conditions  must  be  selected  for 
each  side  of  the  grid,  this  allows  for  consistency  in  the  input  files  for 
both  half-plane  and  full-plane  mode.  I_BC  =  o  is  set  for  land  or  an 
open  boundary.  For  I_BC  =  1,  significant  wave  height,  peak  wave 
period,  and  mean  wave  direction  are  defined  in  the  simulation  file. 
For  I_BC  =  2,  the  wave  spectra  is  specified  in  an  input  spectra  file 
for  every  snap  IDD.  Waves  are  transformed  along  the  lateral 
boundary  for  I_BC  =  3  assuming  the  bathymetry  is  l-D  (adjacent 
boundaries  must  be  I_BC  =  o,  1  or  2).  Only  I_BC  =  o  or  2  is 
available  in  half-plane  mode  with  I_BC  =  2  likely  defined  along  the 
offshore  boundary  and  I_BC  =  o  defined  along  the  lateral 
boundaries. 

Summary  definitions  of  these  and  the  remaining  model  options  are 
provided  in  Table  4  through  Table  19  with  an  example  of  a  simulation  file 
provided  in  Appendix  A. 

Examples  of  IDD_SPEC_TYPE  options  are  provided  in  “IDD_SPEC- 
_TYPE  examples,”  and  further  explanation  of  the  full-plane  iterative 
procedure  can  be  found  in  “Iterative  criteria  and  parallel  execution.” 
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Table  4.  Model  parameters:  Standard  inputs  -  std_parms  namelist. 


Parameter 

Definition 

Comments 

1  PLANE 

=  0  for  half-plane  mode 
=  1  for  full-plane  mode 

IPRP 

=  0  for  propagation  and  wind-wave  generation 
=  1  for  propagation  only 

ICUR 

=  0  for  no  wave-current  interaction 

=  1  for  wave-current  interaction  where  a  current 
field  is  specified  for  each  IDD  (number  of  current 
fields  must  equal  the  number  of  snap  IDD's) 

=  2  for  wave-current  interaction  where  a  single 
current  file  is  specified  for  all  snaps  (one  current 
field  for  all  snap  IDD’s) 

Wave-current  interaction  available  only  for 
half-plane  simulations 

For  ICUR=  1  or  2,  specify  input  file  in 
input_files  namelist  (CURR) 

IBREAK 

=  0  for  no  breaking  indices 
=  1  to  write  0  for  nonbreaking  and  1  for  breaking 
in  each  grid  cell 

=  2  to  print  dissipation  in  each  grid  cell 

Wave  breaking  locations  saved  to  an  output 
breaking  file  (BREAK) 

Specify  name  in  output_files  namelist 

IRS 

=  0  for  no  wave  radiation  stress  calculations 

=  1  to  calculate  and  write  radiation  stress 
gradients 

Radiation  stresses  can  serve  as  input  to  a 
circulation  model  to  force  wave-driven 

currents  and  water  levels 

Saved  to  an  output  radiation  stress  file  (RADS) 
Specify  name  in  output_files  namelist 

NSELCT 

#  =  number  of  optional  (l,J)  grid  cell  output  points 

For  each  output  point,  Hmo,  TP,  and  am  are 
saved  to  a  selected  wave  points  output  file 
(SELH),  spectra  are  saved  to  the  spectral 
output  file  (OBSE) 

Specify  (l,J)  locations  in  select_pts  namelist 
Specify  name  in  output_files  namelist 

NNEST 

#  =  number  of  optional  (l,J)  grid  cell  output  points 
for  nesting  spectra 

Saved  to  nested  output  file  (NEST) 

Specify  (l,J)  locations  in  nest_pts  namelist 
Specify  name  in  output_files  namelist 

NSTATIONS 

#  =  number  of  optional  interpolated  (x,y)  output 
locations 

These  will  be  interpolated  points,  not  (l,J)  grid 
locations,  and  saved  to  the  output  station  file 
(STATION) 

Specify  (x,y)  location  in  stationjocations 
namelist 

Specify  name  in  output_files  namelist 

IBND 

=  0  for  single  point  input  of  spectra  on  boundary 
=  1  linear  interpolation  of  spectra  on  boundaries 

=  2  for  morphic  interpolation  of  spectra  on 
boundaries 

IFRIC 

=  0  for  no  bottom  friction 

=  1  for  constant  JONSWAP  bottom  friction  over  grid 
=  2  for  spatially  variable  JONSWAP  bottom  friction 
over  grid 

=  3  for  constant  Manning  bottom  friction  over  grid 
=  4  for  spatially  variable  Manning  bottom  friction 
over  grid 

For  IFRIC  =  lor  2,  input  value  of  Cf 

For  IFRIC  =  3  or  4,  input  Manning’s  n 

For  IFRIC  =  1  or  3,  coefficient  will  be  entered 
under  the  const_fric  namelist 

For  IFRIC  =  2  or  4,  specify  input  file  in 
input_file  namelist  (FRIC) 

ISURGE 

=  0  for  constant  depth  correction  over  grid 
=  1  for  spatially  variable  depth  correction  over  grid 

For  ISURGE  =  0,  enter  correction  under  the 
const_surge  namelist 
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Parameter 

Definition 

Comments 

For  ISURGE  =  1,  specify  input  file  in  input_files 
namelist  (SURGE) 

IWIND 

=  0  for  constant  wind  over  grid 
=  1  for  spatially  variable  wind  over  grid 

For  IWIND  =  0,  enter  additional  parameters 
under  the  const_wind  namelist 

For  IWIND  =  1,  specify  input  file  in  input_files 
namelist  (WIND) 

IDEPJDPT 

=  0  for  depth  field  to  be  read  from  a  bathymetry 
file 

=  1  for  plane  sloping  bottom 

For  IDEP_0PT  =  0,  specify  input  file  in 
input_files  namelist  (DEP) 

For  IDEP_0PT  =  1,  enter  additional 
parameters  under  the  depth_fun  namelist; 
saves  grid  in  fort.915  file 

I_BC1 

=  0  -  constant  spectrum  set  equal  to  zero 
=  1  -  constant  TMA  spectrum  with  H,  T,  and  wave 
direction  specified 

=  2  -  constant  spectrum  read  in  from  an  input 
spectral  energy  file 
=  3  -  1-D  transformed  spectrum 

For  l_BC  =  0  for  all  grid  boundaries,  waves  will 
be  locally  generated  in  the  modeling  domain; 
additional  parameters  are  required  under  the 
const_spec  namelist 

For  l_BC(ISIDE)  =  1,  enter  additional 
parameters  under  the  const_spec  and 
const_tma_spec  namelist;  only  available  in 
full-plane 

For  l_BC(ISIDE)  =  2,  specify  input  file  in 
input_files  namelist  (SPEC) 

For  LBC(ISIDE)  =  3,  the  adjacent  boundaries 
must  be  0, 1  or  2;  only  available  in  full-plane 

l_BC2 

l_BC3 

l_BC4 

Table  5.  Model  parameters:  Run  time  parameters  -  run_parms  namelist. 


Parameter 

Definition 

Comments 

IDD_SPEC_TYPE 

=  0  -  increment  integer  snap  IDD's 
=  1  -  specified  integer  snap  IDD's 
=  ±  2  -  year  date  format 

=  ±  3  -  local  time  reference 

=  4  -  specified  character  snap  IDD's 

=  0  -  results  in  IDD’s  from  1  to 

NUMSTEPS 

=  1  -  allows  for  non-equally  spaced 
intervals  or  numerical  values  without 
reference  to  time;  enter  information 
under  the  snapjdds  namelist 
=  2  -  intended  for  regular  evenly 
spaced  time  intervals;  enter 
information  under  time_parms 
namelist 

=  -2  -  intended  for  non-regularly 
spaced  time  data;  must  be  enclosed 
in  single  quotes;  enter  information 
under  time_parms  and  snapjdds 
namelists 

=  3  -  intended  for  regular  evenly 
spaced  local  time  intervals;  enter 
information  under  time_parms 
namelist 

=  -3  -  intended  for  non-regularly 
spaced  local  time  data;  must  be 
enclosed  in  single  quotes;  enter 
information  under  time_parms  and 
snapjdds  namelists 
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Parameter 

Definition 

Comments 

=  4  -  allows  for  alpha  numeric 
characters  (20  characters  max);  must 
be  enclosed  in  single  quotes;  enter 
information  under  the  snapjdds 
namelist 

NUMSTEPS 

#  =  number  of  snap  IDD'sto  process 

Required  for  all  IDD_SPEC_TYPE 
values  except  IDD_SPEC_TYPE  =2 

Not  needed  for  coupled  simulations 

N_GRD_PART_I 

#  =  number  of  grid  partitions  in  the  1- 
direction 

(grid  decomposition  and  processor 
specification) 

Only  used  for  parallel  simulations 

Must  be  1  for  half-plane  simulations 
Must  be  an  integer 

Do  not  fall  below  20  cells  per  partition 

N_GRD_PARTJ 

#  =  number  of  grid  partitions  in  the  J- 
direction 

(grid  decomposition  and  processor 
specification) 

Only  used  for  parallel  simulations 

Must  be  an  integer 

Do  not  fall  below  20  cells  per  partition 

N_GRD_PARTJ  x  N_GRID_PART_J  = 
total  number  of  processors  for  parallel 
simulations 

NJNITJTERS 

#  =  maximum  number  of  initial  iterations  to 
perform  per  snap  IDD 

Only  used  for  full-plane  simulations 

Must  be  an  integer 

1 N  IT_ITERS_STOP_VALU  E 

#  =  initial  iterations  stopping  convergence 
criteria  (relative  difference  between 
iterations) 

Only  used  for  full-plane  simulations 

Real  number 

INIT_ITERS_STOP_PERCENT 

#  =  initial  iterations  stopping  percentage 
criteria  (convergent  percent  of  cells  - 
100.0%  or  less) 

Only  used  for  full-plane  simulations 

Real  number 

N_FINAL_1TERS 

#  =  maximum  number  of  final  iterations  to 
perform  per  snap  IDD 

Only  used  for  full-plane  simulations 

Must  be  an  integer 

FI  NAL_ITERS_STOP_VALU  E 

#  =  final  iterations  stopping  convergence 
criteria  (relative  difference  between 
iterations) 

Only  used  for  full-plane  simulations 

Real  number 

FINAL_ITERS_STOP_PERCENT 

#  =  final  iterations  stopping  percentage 
criteria  (convergent  percent  of  cells  - 
100.0%  or  less) 

Only  used  for  full-plane  simulations 

Real  number 

DEFAULT_INPUTJO_TYPE 

=  1  -  all  input  files  are  of  type  ASCII 
=  2  -  all  input  files  are  of  type  BINARY 
(XMDF) 

DEFAULT_OUTPUT_IO_TYPE 

=  0  -  no  output  files  will  be  written 
=  1  -  all  output  files  are  of  type  ASCII 
=  2  -  all  output  files  are  of  type  BINARY 
(XMDF) 

=  3  -  all  output  files  are  saved  as  both  ASCII 
and  BINARY  (XMDF) 
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Table  6.  Model  parameters:  Spatial  grid  parameters  -  spatial_grid_parms  namelist. 


Parameter 

Definition 

Comments 

COORD_SYS 

=  name  of  the  coordinate  system  the  inputs 
are  listed  in  (for  metadata  purposes  only) 

‘STATEPLANE’  -  State  Plane 

‘LOCAL’  -  local  coordinates 

‘UTM’  -  Universal  Transverse 

Mercator 

SPZONE 

#  =  state  plane  zone  code  FIPS  number 

#=  UTM  zone  code 

Only  needed  for  State  Plane  and 
UTM  coordinate  system 

XO 

#  =  x-coordinate  of  the  grid  origin  (m) 

Real  number 

YO 

#  =y-coordinate  of  the  grid  origin  (m) 

Real  number 

AZIMUTH 

#  =  the  azimuth  (rotation)  of  the  grid  in 
degrees,  measured  counterclockwise  from 

East 

Real  number 

DX 

#  =  cell  spacing  (m)  in  the  l-direction 

Real  number 

DX  =  DY  for  half-plane  simulations 

DY 

#  =  cell  spacing  (m)  in  the  J-direction 

Real  number 

DX  =  DY  for  half-plane  simulations 

N_CELL_I 

#  =  number  of  grid  cells  in  the  l-direction 

Must  be  an  integer 

N_CELL_J 

#  =  number  of  grid  cells  in  the  J-direction 

Must  be  an  integer 

Table  7.  Model  parameters:  Input  file  type  -  input_files  namelist. 


Parameter 

Definition 

Comments 

DEP 

Name  of  input  bathymetry  file 

Required  for  IDEP_OPT  =  0 

SURGE 

Name  of  input  water  level  correction  file 

Required  for  ISURGE  =  1 

SPEC 

Name  of  incident  spectral  energy  file 

Required  for  l_BC(ISIDE)  =  2 

WIND 

Name  of  input  wind  file 

Required  for  IWIND  =  1 

FRIC 

Name  of  input  bottom  friction  file 

Required  for  IFRIC  =  2  or  4 

CURR 

Name  of  input  current  file 

Only  used  for  half-plane 
simulations 

Required  for  ICUR  =  1  or  2 

IO_TYPE_DEP 

=  1  -  depth  input  file  type  is  ASCII 
=  2  -  depth  input  file  type  is  BINARY  (XMDF) 

IO_TYPE_SURGE 

=  1  -  surge  input  file  type  is  ASCII 
=  2  -  surge  input  file  type  is  BINARY  (XMDF) 

IO_TYPE_WIND 

=  1  -  wind  input  file  type  is  ASCII 
=  2  -  wind  input  file  type  is  BINARY  (XMDF) 

IO_TYPE_SPEC 

=  1  -  spectral  input  file  type  is  ASCII 
=  2  -  spectral  input  file  type  is  BINARY 
(XMDF) 

IO_TYPE_FRIC 

=  1  -  friction  input  file  type  is  ASCII 
=  2  -  friction  input  file  type  is  BINARY  (XMDF) 

IO_TYPE_CURR 

=  1  -  current  input  file  type  is  ASCII 
=  2  -  current  input  file  type  is  BINARY  (XMDF) 
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Table  8.  Model  parameters:  Ouputfile  type  -  output_files  namelist. 


Parameter 

Definition 

Comments 

WAVE 

Name  of  output  wave  field  file 

Contains  Hmo,  TP,  and  am  for  all  grid 
cells  for  all  snap  IDD's 

OBSE 

Name  of  output  spectral  file 

Only  for  NSELCT>0 

BREAK 

Name  of  output  wave  breaking  file 

Only  for  IBREAK  =  1  or  2 

RADS 

Name  of  output  radiation  stress  file 

Only  for  IRS  =  1 

SELH 

Name  of  selected  wave  points  output  file 

Only  for  NSELCT  >  0 

For  each  output  grid  cell,  Hm o,  TPl  and 
o.m  are  saved 

STATION 

Name  of  output  station  file 

Only  for  NSTATIONS  >  0 

For  each  output  point,  Hmo,  TP,  and  am 
are  saved 

NEST 

Name  of  nested  output  file 

Only  for  NNEST>0 

LOGS 

Name  of  run  time  log  files 

ASCII  files 

TP 

Name  of  output  peak  wave  period  file 

XMDF_SPATIAL 

Name  of  the  XMDF  spatial  output  file 

This  file  only  used  when  IO_TYPE's  are 
set  to  2  or  3. 

IO_TYPE_TP 

=  { 0, 1,  2,  3 }  (see  DEFAULT_OUTPUT_IO_TYPE 
description ) 

Output  file  type  for  the  TP  file;  same 
possible  values  as  in 
DEFAULT_OUTPUT_IO_TYPE 

IO_TYPE_NEST 

=  { 0, 1,  2,  3 }  (see  DEFAULT_OUTPUT_IO_TYPE 
description ) 

Output  file  type  for  the  NEST  file;  same 
possible  values  as  in 
DEFAULT_OUTPUT_IO_TYPE 

IO_TYPE_SELH 

=  { 0, 1,  2,  3 }  (see  DEFAULT_OUTPUT_IO_TYPE 
description ) 

Output  file  type  for  the  SELFI  file;  same 
possible  values  as  in 
DEFAULT_OUTPUT_IO_TYPE 

IO_TYPE_RADS 

=  { 0, 1,  2,  3 }  (see  DEFAULT_OUTPUT_IO_TYPE 
description ) 

Output  file  type  for  the  RADS  file;  same 
possible  values  as  in 
DEFAULT_OUTPUT_IO_TYPE 

IO_TYPE_BREAK 

=  { 0, 1,  2,  3 }  (see  DEFAULT_OUTPUT_IO_TYPE 
description ) 

Output  file  type  for  the  BREAK  file; 
same  possible  values  as  in 
DEFAULT_OUTPUT_IO_TYPE 

IO_TYPE_OBSE 

=  { 0, 1,  2,  3 }  (see  DEFAULT_OUTPUT_IO_TYPE 
description ) 

Output  file  type  for  the  OBSE  file;  same 
possible  values  as  in 
DEFAULT_OUTPUT_IO_TYPE 

IO_TYPE_WAVE 

=  { 0, 1,  2,  3 }  (see  DEFAULT_OUTPUT_IO_TYPE 
description ) 

Output  file  type  for  the  WAVE  file;  same 
possible  values  as  in 
DEFAULT_OUTPUT_IO_TYPE 

IO_TYPE_STATION 

=  { 0, 1,  2,  3 }  (see  DEFAULT_OUTPUT_IO_TYPE 
description ) 

Output  file  type  for  the  STATION  file; 
same  possible  values  as  in 
DEFAULT_OUTPUT_IO_TYPE 
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Table  9.  Model  parameters:  Time  related  parameters  -time_parms  namelist. 


Parameter 

Definition 

Comments 

LTIMEJNC 

#  =  time  increment  between  snap  IDD’s 

Required  when  IDD_SPEC_TYPE  =  ±2 
or  ±3 

For  non-regularly  spaced  data,  enter  1 
Must  be  an  integer 

l_TI  M  E_l  NC_U  N  ITS 

=  units  corresponding  to  time  increment 

‘ss’  =  seconds 

‘mm’  =  minutes 

‘hh’  =  hours 

‘DD’=  days 

Required  when  IDD_SPEC_TYPE  =  ±2 
or  ±3 

Character  data 

IYEAR_START 

=  the  four  digit  year  in  which  the  simulation  starts 

Required  when  IDD_SPEC_TYPE  =  2 

IMON_START 

=  the  two  digit  month  in  which  the  simulation 
starts 

Required  when  IDD_SPEC_TYPE  =  2 

IDAY_START 

=  the  two  digit  day  in  which  the  simulation  starts 

Required  when  IDD_SPEC_TYPE  =  2 

IHR_START 

=  the  two  digit  hour  in  which  the  simulation  starts 

Required  when  IDD_SPEC_TYPE  =  2 

IMIN_START 

=  the  two  digit  minute  in  which  the  simulation 
starts 

Required  when  IDD_SPEC_TYPE  =  2 

ISEC_START 

=  the  two  digit  second  in  which  the  simulation 
starts 

Required  when  IDD_SPEC_TYPE  =  2 

IYEAR_END 

=  the  four  digit  year  in  which  the  simulation  ends 

Required  when  IDD_SPEC_TYPE  =  2 

IM0N_END 

=  the  two  digit  month  in  which  the  simulation  ends 

Required  when  IDD_SPEC_TYPE  =  2 

IDAY_END 

=  the  two  digit  day  in  which  the  simulation  ends 

Required  when  IDD_SPEC_TYPE  =  2 

IHR_END 

=  the  two  digit  hour  in  which  the  simulation  ends 

Required  when  IDD_SPEC_TYPE  =  2 

IMIN_END 

=  the  two  digit  minute  in  which  the  simulation 
ends 

Required  when  IDD_SPEC_TYPE  =  2 

ISEC_END 

=  the  two  digit  second  in  which  the  simulation 
ends 

Required  when  IDD_SPEC_TYPE  =  2 

Table  10.  Model  parameters:  Constant  boundary  spectra  -  const_spec  namelist. 


Parameter 

Definition 

Comments 

NFREQ 

#  =  number  of  frequency  bins 

Required  for  l_BC  =1  or  all  grid 
boundaries  l_BC  =  0 

NA 

#  =  number  of  angle  bands 

Defines  angular  resolution 

Required  for  l_BC  =1  or  all  grid 
boundaries  l_BC  =  0 

NA  =  35  for  half-plane  simulations 

NA  is  typically  set  to  72  for  full-plane 
simulations 

FO 

#  =  lowest  frequency  (Hz) 

Required  for  l_BC  =1  or  all  grid 
boundaries  l_BC  =  0 

DF_CONST 

#  =  constant  frequency  increment 

Required  for  l_BC  =1  or  all  grid 
boundaries  l_BC  =  0 
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Table  11.  Model  parameters:  Analytic  depth  profile  -  depth_fun  namelist. 


Parameter 

Definition 

Comments 

DPJSIDE 

{1,  2,  3,  4}  =  side  of  grid  on  which  depth  D1  is 
defined 

Required  for  IDEPJDPT  =  1 

DP_D1 

#  =  water  depth  (m)  on  ISIDE 

Required  for  IDEPJDPT  =  1 

DP_SLOPE 

#  =  constant  bed  slope  applied  from  ISIDE 
across  the  grid 

Required  for  IDEP_OPT  =  1 

Table  12.  Model  parameters:  Constant  bottom  friction  -  const_fric  namelist. 


Parameter 

Definition 

Comments 

cf_const 

#  =  constant  JONSWAP  or  Manning  bottom 
friction  value 

Required  for  IFRIC  =  1  or  3 

Table  13.  Model  parameters:  Snap  IDD's  -  snapjdds  extra  namelist. 


Parameter 

Definition 

Comments 

IDDS  (NUMSTEPS) 

=  time/case  event  identifier  for  each  snap  IDD 

Required  for  IDD_SPEC_TYPE  =  1,  -2, 
-3,  or  4 

IDD_SPEC_TYPE  =  1  is  for  integer 
data 

IDD_SPEC_TYPE  =  -2  or  -3  is  for 
integer  or  character  data  (20 
characters  max),  both  enclosed  in 
single  quotes 

IDD_SPEC_TYPE  =  4  is  for  character 
data  (20  characters  max)  enclosed  in 
single  quotes 

Must  appear  as  single  column 

Table  14.  Model  parameters:  Selected  points  -  select_pts  extra  namelist. 


Parameter 

Definition 

Comments 

lOUT(NSELCT), 

JOUT(NSELCT) 

#  =  (l,J)  grid  cell  locations  for  selected  output 
points 

Required  for  NSELCT  >  0 

To  save  Hm o,  TPl  and  am  as  well  as 
spectra 

Must  appear  as  two  column  pairs 

Table  15.  Model  parameters:  Nest  points  -  nest_pts  extra  namelist. 


Parameter 

Definition 

Comments 

INEST(NNEST), 

JNEST(NNEST) 

#  =  (l,J)  grid  cell  locations  to  save  spectra  for 
nesting  application 

Required  for  NNEST  >  0 

Must  appear  as  two  column  pairs 
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Table  16.  Model  parameters:  Station  points  -  stationjocations  extra  namelist. 


Parameter 

Definition 

Comments 

STAT_XCOOR(NSTATIONS), 

STAT_YCOOR(NSTATIONS) 

#  =  (x,y)  coordinates  of  station  output 
locations 

Required  for  NSTATIONS  >  0 

Real  numbers 

Must  appear  as  two  column 
pairs 

Table  17.  Model  parameters:  Spatially  constant  winds  -  const_wind  extra  namelist. 


Parameter 

Definition 

Comments 

UMAG_CONST_IN(NUMSTEPS), 

UDIR_CONST_IN(NUMSTEPS) 

#  =  magnitude  (UMAG_CONSTJN)  and 
direction  (UDIR_CONST_IN)  for  spatially 
constant  winds 

Required  for  IWIND  =  0 

Real  numbers 

Must  appear  as  two  column 
pairs 

Table  18.  Model  parameters:  Spatial  water  level  adjustment  -  const_surge  extra  namelist. 


Parameter 

Definition 

Comments 

DADD_CONST_l  N(N  UMSTEPS) 

#  =  spatially  constant  water  level  height 
adjustment 

Required  for  ISURGE  =  0 

Real  number 

Must  appear  as  single  column 

Table  19.  Model  parameters:  TMA  boundary  spectra  -  const_tma_spec  extra  namelist. 


Parameter 

Definition 

Comments 

H_SPECJN(NUMSTEPS,ISIDE), 

TP_SPEC_IN(NUMSTEPS,ISIDE), 

WVANG_SPECJN(NUMSTEPS,ISIDE) 

#  =  constant  boundary  spectra 
wave  height  (m)  -  H  J3PECJN 
peak  period  (s)  -  TPJ5PECJN 
wave  direction  (deg)  -  WVANGJ3PECJN 

Require  when  l_BC(ISIDE)  = 

1  where  ISIDE  =  1,  2,  3,  or  4 
(boundary  sides  of  the 
domain) 

Real  numbers 

Must  appear  as  three 
column  triplets 

IDD_SPEC_TYPE  examples 

In  order  to  provide  for  easy  setup  as  well  as  detailed  control,  there  are 
seven  options  for  naming  snap  IDD’s  (o,  l,  ±  2,  ±  3,  and  4).  The  simulation 
file  and  results  of  each  selection  is  shown  below  to  further  clarify  these 
options. 


IDD  SPEC  TYPE  =  O 


&run_parms 
idd  spec  type  =  0, 
numsteps  =  3, 


IDDS 

Results 


1 

2 

3 
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IDD  SPEC  TYPE  =  l 


&run_parms 
idd  spec  type  =  1, 
numsteps  =  3, 

/ 

@snap_idds 
idds (1)=  89, 
idds (2) =  367, 
idds ( 3 ) =  678 

/ 


IDD  SPEC  TYPE  = -2 


&run  parms 

idd  spec  type  =  -2, 

numsteps  = 

3, 

/ 

&time  parms 

i  time  inc 

units  =  'DD' 

/  " 

@snap  idds 

idds ( 1 )  = 

’20101225’ , 

idds (2)  = 

’20101226’ , 

idds (3)  = 

'20101229' 

/ 

IDDS 

Results 


89 

367 

678 


IDDS 

Results 


20101225 

20101226 

20101229 


IDD_SPEC_TYPE  =  2 


&run  parms 

idd  spec  type  =  2, 

/ 

&time  parms 

i  time  inc 

=  30, 

i  time  inc 

units  =  'mm' , 

iyear  start 

.  =  2016, 

imon  start 

=  07, 

iday  start 

=  31, 

ihr  start  = 

03, 

imin  start 

=  00, 

isec  start 

=  00, 

iyear  end  = 

:  2016, 

imon  end  = 

CO 

o 

iday  end  = 

02, 

ihr  end  =  01, 

imin  end  = 

o 

o 

isec  end  = 

00 

/ 

IDDS 

Results 


20160731030000 

20160731033000 

20160731040000 
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IDD_SPEC_TYPE  =  -3 


&run_parms 
idd_spec_type  =  -3, 
numsteps  =  3, 

/ 

&time  parms 

i  time  inc  units  =  'hh' 

/ 

@snap  idds 
idds(l)  =  ’0100', 
idds (2)  =  ’0500', 
idds ( 3 )  =  ’1200' 

/ 


IDDS 

Results 


0100 

0500 

1200 


IDD_SPEC_TYPE  =  3 


&run_parms 
idd  spec  type  =  3, 
numsteps  =  3, 

/ 

&time_parms 
i_time_inc  =  30, 
i_time_inc_units  =  'mm' 

/ 


IDDS 

Results 


o 

30 

60 


IDD_SPEC_TYPE  =  4 


&run  parms 

idd  spec 

type  =  4, 

numsteps 

=  3, 

/ 

@snap  idds 

idds ( 1 )  = 

'Sept', 

idds (2)  = 

'  abc '  , 

idds ( 3 )  = 

/ 

'  sim5  ' 

IDDS 

Results 


Sept 

abc 

sim5 


Iterative  criteria  and  parallel  execution 

The  solution  process  for  the  full-plane  version  of  STWAVE  is  an  iterative 
process  that  requires  a  convergent  state  to  signal  that  a  suitable  solution 
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has  been  achieved.  The  process  is  divided  into  two  states,  an  initial  and  a 
final  sweep  stage.  During  the  initial  iterative  sweep,  boundary  spectra 
information  is  simply  propagated  from  the  boundary  throughout  the 
domain.  Once  this  stage  reaches  convergence,  winds  and  surges  are  added 
to  the  forcing  in  the  final  sweep  stage,  and  this  stage  iteratively  executes 
until  it  also  reaches  a  convergent  state. 

These  convergent  states  are  defined  by  the  user  in  the  simulation  file 
under  the  run_parms  namelist.  The  convergence  criteria  for  the  full- 
plane  version  of  STWAVE  are: 

N_INIT_ITERS  -  maximum  number  of  initial  iterations  to  perform  per 
snap  IDD 

INIT_ITERS_STOP_VALUE  -  relative  difference  between  initial 
iterations 

INIT_ITERS_STOP_PERCENT  -  minimum  percent  of  cells  that  must 
satisfy  stopping  criteria  for  initial  iterations 

N_FINAL_ITERS  -  maximum  number  of  final  iterations  to  perform  per 
snap  IDD 

FINAL_ITERS_STOP_VALUE  -  relative  difference  between  final 
iterations 

FINAL_ITERS_STOP_PERCENT  -  minimum  percent  of  cells  that  must 
satisfy  stopping  criteria  for  final  iterations 

During  a  single  iteration,  energy  propagation  can  only  cross  one  grid 
partition  at  a  time.  As  a  result,  the  maximum  number  of  initial/final 
iterations  should  be  set  to  a  value  of  at  least  5-10  larger  than  the  largest  grid 
partition  (e.g.,  a  domain  partitioned  4  times  in  the  I-direction  and  10  times 
in  J-direction  should  have  the  maximum  number  of  iterations  be  no  less 
than  15).  These  are  fail  safe  stopping  values  since  it  limits  the  number  of 
iterations  calculated  but  convergence  could  still  be  reached  before  this 
number. 
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The  average  wave  height  for  each  cell  is  the  stopping  criteria  monitored  for 
convergence.  The  relative  change  in  average  wave  height  between 
iterations  is  checked  by  the  following  scheme: 


Jin  1 

#ti,i 

hn 

#ti,i 

h?'1 

h" 

1,2 

Hn  = 

*1.2 

hnl 

hn 

ilni,nj 

ilni,nj 

Hn-Hnl 
avg(H")  ’ 


Average  wave  height  at  iteration  Average  wave  height  at  Relative  change  in  average  wave 

(n-1)  iteration  (n)  height  between  iterations  (n  and  n-1) 


where: 


H  =  average  wave  height  for  an  iteration, 
h  =  individual  grid  cell  wave  height, 

NI  =  total  grid  cells  in  I-direction, 

NJ  =  total  grid  cells  in  J-direction, 

R  =  relative  change  in  average  wave  height. 

The  STOP_PERCENT  is  defined  as  the  minimum  percent  of  cells  that 
must  satisfy  the  STOP_VALUE  for  convergence.  Thus,  when 
STOP_PERCENT  of  the  cells’  ^-values  are  less  than  the  STOP_VALUE, 
the  solution  has  converged.  The  relative  difference  between  iterations  or 
STOP_VALUE  should  be  defined  as  a  value  between  0.05  and  0.1  with  the 
STOP_PERCENT  of  grid  cells  defined  close  to  100.0  (98.5  -  100.0).  The 
smaller  the  maximum  relative  difference  (STOP_VALUE),  the  more  final 
iterations  are  performed  and  as  a  result  the  more  simulation  time 
STWAVE  requires. 

The  parallelized  in  time  feature  of  STWAVE  uses  a  time  decomposition  of 
the  snaps  whereby  each  snap  is  completed  on  its  own  processor  using  a 
single  grid.  Essentially  what  happens  is  that  a  distribution  of  serial 
executions  is  performed  whereby  each  snap  IDD  has  its  own  dedicated 
processor.  For  example  a  job  with  50  snaps  would  require  the  use  of 
50  processors  with  each  processor  performing  only  one  snap. 

The  parallelized  in  space  capability  of  STWAVE  uses  domain  decomposition 
where  the  STWAVE  domain  is  divided  into  smaller  grid  chunks  called 
partitions.  As  previously  stated,  half-plane  simulations  can  only  be  divided 
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in  the  J-direction  while  full-plane  simulations  can  be  divided  in  the  I-  and  J- 
directions.  The  number  of  computer  processors  required  for  a  parallelized 
STWAVE  simulation  is  dictated  by  the  number  of  partitions  specified  in  the 
simulation  file  under  the  run_parms  namelist, 

N_GRID_PART_I  -  number  of  grid  partitions  in  the  I-direction,  =  l  for 
half-plane 

N_GRID_PART_J  -  number  of  grid  partitions  in  the  J-direction 

where  the  total  number  of  processors  used  is  the  product  of  the  partitions, 

Number  of  Processors  =  N_GRID_PART_I  x  N_GRID_PART_J.  (24) 

For  example,  if  a  grid  is  partitioned  into  three  parts  in  the  I-direction  and 
five  parts  in  the  J-direction,  then  15  processors  are  required  for  the 
STWAVE  simulation.  DO  NOT  use  less  than  20  cells  per  partition 
dimension  when  deciding  on  how  to  divide  the  grid.  Note  for  the  full-plane 
option,  while  increasing  the  number  of  processors  does  require  more 
iterations  to  reach  convergence  it  still  requires  less  wall-clock  time  to  reach 
a  solution. 

Sensitivity  to  final  convergence  criteria  and  number  of  processors 

Full-plane  STWAVE  operates  using  an  iterative  algorithm  whereby  a  set  of 
user-defined  iterative  controls,  such  as  number  of  iterations  and  stopping 
criteria,  are  imposed  to  signal  the  convergence  of  a  suitable  solution.  As  a 
result,  the  performance  behavior,  running  time,  and  accuracy  of  the 
solution  are  dependent  on  these  parameters.  The  use  of  spatially  varying 
wind  and  surge  fields,  such  as  those  used  for  hurricane  simulations, 
typically  causes  the  model  to  “work  harder”  at  deriving  a  converged 
solution  and  shows  more  sensitivity  to  the  stopping  criteria  than  spatially 
constant  wind  and  surge  fields.  This  section  provides  a  detailed  analysis 
whereby  the  final  stopping  criteria  are  varied  in  order  to  determine  the 
solution  sensitivity  to  such  differences.  In  addition  to  stopping  criteria,  the 
analyses  consider  the  parallel  in  space  component  and  address  how  the 
solution  is  affected  by  decomposing  the  domain  into  different  numbers  of 
partitions.  The  tests  were  performed  using  different  intensity  synthetic 
hurricane  simulations,  one  making  landfall  in  southeastern  Louisiana  and 
another  along  the  Texas  coast  near  Port  Aransas. 
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Louisiana  SE  grid 

The  Louisiana  SE  grid  is  comprised  of  683  cells  in  the  I-direction  and  744 
cells  in  the  J-direction  with  the  cell  spacing  in  both  directions  set  at  200.0 
m.  Note  in  Figure  5  that  the  model  domain  includes  both  water  and  land 
cells,  with  land  appearing  in  brown.  Cells  that  are  dry  (land)  are  not  active 
during  a  snap.  However,  due  to  time  varying  storm  surge  values,  dry  cells 
can  become  inundated  and  are  then  made  active.  The  model  input 
conditions  are  those  of  a  synthetic  hurricane  with  wind  fields  supplied  from 
a  planetary  boundary  layer  model  (MORPHOS  PBL),  spectral  boundary 
conditions  supplied  from  a  larger  scale  wave  model  simulation  using  the 
WAM  model  (Komen  et  al.  1994),  and  surge  values  supplied  from  ADCIRC. 
The  spatially-averaged  characteristics  of  the  Louisiana  simulation  input 
over  the  97  snaps  are  shown  in  Figures  6  through  Figure  9.  The  average 
wave  height  is  shown  in  Figure  10.  All  the  parallel  test  cases  were  run  using 
the  ERDC  DSRC  high  performance  computing  resources;  in  particular  all 
parallel  simulations  were  completed  using  the  Cray  XT4  computer  known  as 
Jade.  Jade  has  2,146  compute  nodes  with  each  node  containing  a  2.1-GHz 
AMD  Opteron  64-bit  quad-core  processors  and  8  GBytes  of  dedicated 
memory  (http://www.erdc.hpc.mil/).  The  nodes  are  networked  together  using  a 
Cray  SeaStar2  communications  engine.  The  STWAVE  source  code  was 
compiled  using  the  Portland  Group  (PGI)  10.3.0  FORTRAN  compiler  and 
the  MPICH-2  implementation  for  MPI.  Due  to  the  high  memory 
requirements  for  the  serial  test  cases,  those  simulations  were  performed  on 
a  Linux  workstation  with  dual  2.8  GHz  quad-core  AMD  Opteron  processors 
with  512  KB  of  Cache,  a  total  of  24  GB  of  system  memory  and  using  the 
64-bit  OpenSuse  11.0  Linux  operating  system.  The  STWAVE  source  code 
was  compiled  using  GNU  FORTRAN  4.2. 

Table  20  shows  the  tested  combination  of  grid  decompositions  and  stopping 
values  used  in  this  sensitivity  analysis.  The  grid  partition  size  is  dictated  by  a 
desire  to  keep  the  partitions  as  square  as  possible  without  falling  below  the 
20  cell  per  partition  limit.  The  final  stopping  criteria  (denoted  by  EF  in  the 
table)  consist  of  the  pair  of  variables  FINAL_ITERS_STOP_VALUE  and 
FINAL_ITERS_PERCENT_VALUE.  The  stop  value  is  the  relative 
difference  between  iterations,  R,  and  must  be  in  the  range  of  o. 0-1.0.  The 
percentage  value  is  between  0.0-100.0  and  governs  the  amount  of  cells  that 
must  be  less  than  or  equal  to  the  stop  value  in  order  to  exit  the  iteration 
scheme. 
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Figure  5.  Bathymetry  contours  for  the  Louisiana  grid. 


Figure  6.  Percentage  of  wet  cells  (active)  for  each  snap  for  the  Louisiana  grid. 


Figure  7.  Maximum  surge  levels  (meters)  over  the  grid  for  each  snap  in  the  Louisiana  grid. 
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Figure  9.  Mean  wind  direction  (degrees)  over  the  grid  for  each  snap  in  the  Louisiana  grid. 


Figure  10.  Average  wave  height  for  each  snap  for  the  Louisiana  grid. 
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Table  20.  Parameters  used  for  sensitivity  tests  on  the  Louisiana  grid. 


Run  Number 

Grid  Partitioning  (Nix  Nj) 

No.  of  Processors 

EF 

B 

lxl 

1 

0.1,  99.8 

1 

11  x  12 

132 

0.1,  99.8 

2 

14  x  15 

210 

0.1,  99.8 

3 

17x19 

323 

0.1,  99.8 

4 

22x24 

528 

0.1,  99.8 

S2 

lxl 

1 

0.05,  99.8 

5 

11  x  12 

132 

0.05,  99.8 

6 

14  x  15 

210 

0.05,  99.8 

7 

17  x  19 

323 

0.05,  99.8 

8 

22x24 

528 

0.05,  99.8 

S3 

lxl 

1 

0.1,  99.5 

9 

11  x  12 

132 

0.1,  99.5 

10 

14  x  15 

210 

0.1,  99.5 

11 

17x19 

323 

0.1,  99.5 

12 

22x24 

528 

0.1,  99.5 

As  a  first  analysis,  total  computational  times  are  compared  for  all  test 
cases  listed  in  Table  20  in  order  to  determine  the  effect  of  grid  partitioning 
and  EF  values  on  execution  time.  The  results  for  total  computation  times 
are  illustrated  in  Figure  11.  As  the  number  of  processors  increases,  the 
overall  execution  time  of  STWAVE  decreases.  This  indicates  that  dividing 
the  STWAVE  domain  into  smaller  grid  partitions  results  in  a  faster  overall 
execution  (wall-clock)  time  -  for  example,  increasing  the  partitions  from 
11  x  12  to  22  x  24  reduced  the  running  time  by  approximately  a  third. 
While  a  linear  speedup  is  not  achieved,  the  time  advantages  and  lessened 
per  processor  memory  requirements  are  substantial. 
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Figure  11.  Wall  clock  time  for  computing  97  snaps  on  the  Louisiana  grid. 
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Returning  to  Figure  11,  it  is  also  seen  that  longer  running  times  are 
required  for  stricter  stopping  criteria.  The  running  times  required  for  a 
stop  percent  of  99.8  is  slightly  longer  than  for  a  stop  percent  of  99.5  for  all 
processors  considering  the  same  relative  difference.  In  addition,  a  smaller 
relative  difference  (0.05)  has  a  slower  completion  time  than  a  higher 
relative  difference  (0.10)  for  the  same  stop  percent.  However,  the 
magnitude  of  difference  between  wall  times  decreases  as  the  number  of 
processors  increase.  The  time  difference  between  an  EF  of  (0.1,  99.5)  and 
an  EF  of  (0.1,  99.8)  is  about  15  min  at  132  processors  and  nearly  negligible 
at  528  processors.  Similarly,  the  time  difference  between  an  EF  of  (0.1, 
99.8)  and  (0.05,  99.8)  is  approximately  40  min  at  132  processors  and  less 
than  10  min  at  528  processors.  It  should  be  noted  that  wall  time  appears  to 
be  more  sensitive  to  relative  difference  than  stop  percent,  particularly  for  a 
smaller  number  of  processors,  given  that  the  largest  time  differences  result 
from  tightening  the  relative  difference. 

Looking  at  the  individual  iteration  level  by  taking  average  overall 
iterations  performed  for  the  97  snaps,  it  is  apparent  that  the  completion 
time  per  iteration  is  considerably  higher  when  STWAVE  is  run  in  serial 
mode  (one  processor)  compared  with  parallel  mode  (multiple  processors). 
The  time  per  iteration  continues  to  decrease  gradually  as  the  number  of 
processors  increase,  as  seen  in  Figure  12,  indicating  more  processors  (i.e., 
finer  grid  partitions)  accelerate  the  computations. 


0  100  200  300  400  500  600 

No.  of  Processors 


Figure  12.  Average  time  per  iteration  versus  the  number  of  processor  for  the  Louisiana  grid. 

Another  consideration  is  the  required  iteration  count  per  snap  to  satisfy 
the  convergence  criteria.  For  all  test  cases  performed  here,  the  number  of 
iterations  performed  per  snap  tends  to  increase  towards  the  end  of  the 
simulation  time,  e.g.,  the  later  snaps.  This  is  mainly  due  to  the  number  of 
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active  cells  (i.e.,  wet  areas  of  the  domain)  increasing  as  the  hurricane 
makes  landfall  and  the  surge  propagates  inland.  This  increase  in  the  total 
number  of  active  cells  requires  STWAVE  to  perform  more  iterations  per 
snap  in  order  to  reach  the  required  convergence  criteria.  The  percentage  of 
wet  cells  as  a  function  of  snap  number  is  shown  in  Figure  6  with  the 
number  of  iterations  per  snap  for  all  cases  shown  in  Figure  13. 

More  iterations  and  variability  in  iteration  count  is  observed  for  the  case 
where  the  smallest  maximum  difference  (0.05)  is  used.  The  variability  in 
iteration  count  shows  the  effort  of  STWAVE  to  converge  on  a  solution 
subjected  to  a  smaller  difference  between  cells,  and  indicates  that  relative 
difference  has  a  greater  impact  on  the  iteration  count  than  the  percentage 
of  cells  criteria.  The  time  required  to  obtain  a  suitable  solution  is  directly 
influenced  by  the  iteration  count,  which  explains  why  the  simulations  with 
an  R  of  0.05  for  FINAL_ITERS_STOP_VALUE  had  the  longest  wall  clock 
time.  Finally,  it  is  observed  that  using  more  grid  partitions  tends  to  require 
more  iteration  per  snap,  particularly  in  conjunction  with  stricter  stopping 
criteria. 

Four  representative  snap  solutions  are  selected  to  observe  how  the 
solution  itself  varied  with  different  convergence  criteria  and  grid 
decomposition.  The  four  snaps  selected  span  the  simulation  event.  One 
occurs  early  in  the  storm,  the  next  one  is  just  before  the  peak  surge,  the 
third  is  just  after  the  peak  surge,  and  the  final  one  is  after  the  eye  of  the 
storm  has  passed  beyond  the  computational  domain.  Solutions  are 
compared  with  a  base  simulation  run  on  a  personal  computer  in  serial 
mode  with  EF  =  (0.1,  99.8).  Although  output  was  obtained  at  all  four 
snaps,  significant  differences  are  observed  between  cases  for  snap  97, 
therefore,  the  comparisons  will  focus  on  snap  97  and  the  changes  observed 
as  a  result  of  the  test  specifications. 

Figure  14  shows  the  wave  height  variations  between  different  stopping 
criteria  for  snap  97  using  the  serial  method.  No  significant  differences 
among  the  three  solutions  are  noted,  suggesting  that  changing  the 
stopping  criteria  for  final  iterations  would  not  provoke  significant  changes 
in  wave  height  when  only  one  processor  is  used  for  execution.  The  only 
noticeable  difference  among  the  serial  simulations  is  the  wall  time 
required  to  achieve  them;  where,  as  expected,  the  slowest  and  longest  wall 
times  correspond  to  an  EF  =  (0.1,  99.5)  and  (0.05,  99.8),  respectively. 
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For  the  parallel  simulations,  differences  between  each  case  as  a  result  of 
changes  in  both  the  number  of  processors  and  the  stopping  criteria  are 
observed.  Using  a  greater  maximum  relative  change  of  o.i  for  the  final 
iterations  and  then  distributing  the  calculations  amongst  several 
processors  results  in  an  underpredicted  wave  height  field  when  compared 
with  the  base  simulation.  Additionally,  using  the  less  stringent  R  =  o.i,  in 
combination  with  a  higher  number  of  processors,  causes  apparitions  of 
blocks  to  appear  in  the  wave  height  solution  (wave  heights  are  not 
continuous  across  the  blocks).  The  appearance  of  these  blocks  indicates 
that  the  stopping  criteria  were  not  sufficient  to  produce  a  reasonable 
solution.  As  a  result,  when  the  iterations  stopped,  the  final  solutions  of 
each  individual  grid  partition  did  not  match  completely  the  values  of  their 
neighbors  along  the  grid  partition  boundaries.  This  caused  discontinuities 
along  the  grid  partition  boundaries  in  the  combined  final  solution  and 
hence,  the  appearance  of  blocks  in  the  contour  plots.  Comparing  Figure  15 
and  Figure  16,  it  is  notable  that  the  stopping  criteria  EF  =  (0.05,  99.8) 
provides  the  best  solution  independent  of  the  number  of  processors  when 
compared  to  the  serial  runs.  Specifically,  the  blocks  tend  to  disappear  and 
the  wave  height  fields  more  closely  match  those  of  the  base  simulation.  No 
significant  disparities  between  solutions  are  observed  between  an  EF  of 
99.8  and  99.5,  which  equates  to  a  difference  of  about  1,524  cells,  indicating 
that  small  changes  in  the  percentage  of  cells  that  meet  the  relative 
difference  does  not  make  a  considerable  impact  on  the  final  solution,  at 
least  for  the  Louisiana  grid  being  analyzed  here. 

Differences  in  average  wave  height  solutions  as  a  result  of  varying 
convergence  criteria  are  shown  in  Figure  17.  The  larger  magnitudes  and 
fluctuations  are  associated  with  the  maximum  relative  difference  R,  which 
clearly  indicates  the  solution  is  more  sensitive  to  the  maximum  relative 
difference  rather  than  the  percentage  of  cells  satisfying  the  stop  value.  It  is 
important  to  note  that  while  the  solution  is  affected  by  convergence  criteria, 
the  maximum  wave  height  difference  is  approximately  5  cm,  which  is 
comparatively  small  considering  the  average  wave  heights  of  the  modeled 
storm  were  between  1.0  and  2.6  m,  as  shown  in  Figure  10. 
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Figure  13.  Iteration  counts  per  snap  for  different  run  conditions  for  the  Louisiana  grid. 
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Figure  14.  Wave  heights  (meters)  for  snap  97  from  the  serial  mode  runs  for  the  Louisiana 

grid. 


Texas  grid 

The  Texas  coastline  grid  consists  of  255  cells  in  the  I-direction  and  360  cells 
in  the  J-direction  with  a  cell-spacing  of  200.0  m  in  both  directions.  The 
topography  and  bathymetry  contours  are  shown  in  Figure  18.  The  model 
input  conditions  are  those  of  a  synthetic  hurricane  with  wind  fields  supplied 
from  a  planetary  boundary  layer  model  (MORPHOS  PBL),  spectral 
boundary  conditions  supplied  from  a  larger  scale  WAM  simulation,  and 
surge  fields  supplied  from  ADCIRC.  Spatially  averaged  values  of  the  input 
characteristics  on  the  Texas  grid  are  shown  in  Figure  19  through  Figure  22. 
The  tested  model  control  conditions  are  shown  in  Table  21.  The  analyses 
with  the  Texas  grid  is  meant  to  act  as  a  supplement  for  the  Louisiana  grid, 
and  mainly  addresses  wall  time  and  solution  sensitivities  to  the  model 
control  parameters.  The  base  case  for  this  grid  is  the  serial  case,  EF  =  (0.1, 
99.8)  simulation. 
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Figure  15.  Contours  of  wave  height  for  snap  97  on  the  Louisiana  grid  for  different  EF  values 
for  132  processors  and  210  processors. 
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Figure  16.  Contours  of  wave  height  for  snap  97  on  the  Louisiana  grid  for  different  EF  values 
for  323  processors  and  528  processors. 
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Figure  17.  Comparisons  of  difference  in  average  wave  height  (meters)  for  the  Louisiana  grid. 
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Figure  18.  Bathymetry/topography  contours  for  the  Texas  grid. 
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Snap  Number 


Figure  19.  Percent  of  wet  (active)  cells  for  each  snap  for  the  Texas  case. 


Figure  20.  Maximum  surge  levels  (meters)  over  the  grid  for  each  snap  in  the 

Texas  case. 
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Figure  21.  Maximum  wind  speed  (meters/second)  over  the  grid  for  each  snap  in 

the  Texas  case. 


Figure  22.  Mean  wind  direction  (degrees)  over  the  grid  for  each  snap  in  the 

Texas  case. 


All  the  Texas  grid  simulations,  both  serial  and  parallel,  were  performed 
using  the  ERDC  DSRC  high  performance  computing  resources. 

Specifically  the  SGI  Altix  ICE  machine  known  as  Diamond  was  used. 
Diamond  contains  1,920  compute  nodes  (15,360  compute  cores).  Each 
compute  node  contains  two  2.8-GHz  Intel  Xeon  64-bit  quad-core  Nehalem 
processors  and  24  GBytes  of  dedicated  memory.  The  nodes  are  connected 
to  each  other  in  a  HyperCube  topology  DDR  4X  InfiniBand  network.  The 
STWAVE  source  code  was  compiled  using  the  version  11.1.074  Intel 
Fortran  compiler  and  the  MPICH-2  implementation  of  MPI. 
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Table  21.  Parameters  used  for  sensitivity  tests  on  the  Texas  grid. 


Run  Number 

Grid  Partitioning  (Nix  Nj) 

No.  of  Processors 

EF 

B 

lxl 

1 

0.1,  99.8 

1 

2x3 

6 

0.1,  99.8 

2 

4x6 

24 

0.1,  99.8 

3 

6x9 

54 

0.1,  99.8 

4 

8x11 

88 

0.1,  99.8 

5 

12x17 

204 

0.1,  99.8 

S2 

lxl 

1 

0.05,  99.8 

6 

2x3 

6 

0.05,  99.8 

7 

4x6 

24 

0.05,  99.8 

8 

6x9 

54 

0.05,  99.8 

9 

8x11 

88 

0.05,  99.8 

10 

12x17 

204 

0.05,  99.8 

S3 

lxl 

1 

0.1,  99.5 

11 

2x3 

6 

0.1,  99.5 

12 

4x6 

24 

0.1,  99.5 

13 

6x9 

54 

0.1,  99.5 

14 

8x11 

88 

0.1,  99.5 

15 

12x17 

204 

0.1,  99.5 

S4 

lxl 

1 

0.05,  99.5 

16 

2x3 

6 

0.05,  99.5 

17 

4x6 

24 

0.05,  99.5 

18 

6x9 

54 

0.05,  99.5 

19 

8x11 

88 

0.05,  99.5 

20 

12x17 

204 

0.05,  99.5 

As  in  the  Louisiana  case,  the  same  pattern  for  total  wall  clock  time  versus 
number  of  processors  is  observed  for  the  smaller  Texas  grid,  shown  in 
Figure  23.  The  total  time  decreases  as  the  number  of  processors  increases, 
and  stricter  final  convergence  criteria  require  longer  running  times  using 
the  same  number  of  processors.  The  greatest  increase  in  run  time  occurs 
when  the  maximum  relative  difference  is  reduced  from  0.10  to  0.05  for  a 
cell  percentage  of  99.8.  The  difference  in  run  time  becomes  less  substantial 
when  more  processors  are  used. 
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No.  of  Processors 


Figure  23.  Total  wall  clock  time  (minutes)  for  different  run  parameters  for  the  Texas  grid. 

The  difference  between  wave  height  fields  due  to  convergence  criteria  and 
domain  decomposition  is  further  addressed  by  this  analysis.  The 
maximum  wave  height  occurred  at  snap  36  and  this  snap  is  considered  for 
investigating  the  sensitivity  due  to  changes  in  grid  partitioning  and 
convergence  criteria.  In  Figure  24  a  contour  plot  of  the  wave  height  field 
for  snap  36  is  shown  for  the  base  run  parameters,  EF=(o.i,99.8).  The  plots 
for  the  other  serial  cases  are  nearly  indistinguishable  from  the  base  and 
are  not  shown.  In  Figure  25  through  Figure  27  spatial  plots  showing  the 
difference  in  wave  height  solutions  between  the  serial  and  parallel 
simulations  of  the  same  convergence  criteria  are  presented.  In  general, 
differences  between  the  serial  and  parallel  wave  fields  increase  as  the 
number  of  processors  increase,  and  there  tends  to  be  a  persisting 
underestimation  of  wave  heights  within  the  inland  water  bodies  across  all 
processors.  This  is  clearly  seen  in  the  darker  blue  color  of  Figure  26  as 
compared  to  Figure  25.  Similar  to  the  Louisiana  grid,  partition  blocks 
become  noticeable  at  the  greatest  processor  number  (204  processors)  for 
the  lower  R-v alue  of  0.1.  These  blocks  indicate  the  EF  criteria  were  not 
sufficient  to  allow  the  matching  of  solutions  between  grid  partitions. 
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Figure  24.  Wave  height  (meters)  for  snap  36  of  the  Texas 
case,  using  the  serial  base  case  of  EF=(0.1,  99.8). 


Next,  in  order  to  further  evaluate  convergence  criteria,  only  the  serial 
simulations  are  considered  to  eliminate  the  discrepancies  resulting  from 
number  of  processors.  It  is  observed  that  tightening  the  maximum  relative 
difference  R  to  0.05  resulted  in  a  slightly  higher  predicted  wave  height  for 
a  cell  percentage  of  99.8  and  99.5.  However,  no  differences  between  the 
solutions  were  seen  by  decreasing  the  cell  percentage  from  99.8  to  99.5,  a 
change  of  only  275  cells,  while  maintaining  the  same  /?-value.  Figure  28 
shows  this  behavior  for  snap  36.  This  behavior  supports  the  assertion  that 
the  STWAVE  solution  is  more  influenced  by  the  maximum  relative 
difference  between  cells  than  the  percentage  of  cells  satisfying  the 
stopping  criteria,  at  least  for  the  values  considered  herein.  The  maximum 
difference  between  any  solutions  was  roughly  5  cm,  which  represents  a 
larger  percentage  of  the  average  wave  height  (0.12  -  0.36  m)  than  that 
seen  in  the  Louisiana  grid.  A  time  series  plot  showing  the  average  wave 
height  over  the  entire  grid  for  each  snap  is  shown  in  Figure  29. 
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Figure  25.  Difference  in  wave  height  (meters)  for  6  and  24  processors  of  the  same  EF  criteria. 
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Figure  26.  Difference  in  wave  height  (meters)  for  54  and  88  processors  of  the  same  EF 

criteria. 
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Figure  27.  Difference  in  wave  height  (meters)  for  204 
processors  of  the  same  EF  criteria. 
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Figure  28.  Difference  in  wave  height  (meters)  versus  EF 
value  for  serial  runs. 
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Figure  29.  Average  wave  height  (meters)  over  the  grid  for  each  snap  in  the  Texas 

case. 


Recommendations 

Simulating  nearshore  hurricane  waves  using  STWAVE  showed  slightly 
different  solutions  depending  on  the  number  of  processors  and  the 
convergence  criteria  when  calculating  the  final  iterations.  As  a  result, 
sufficient  convergence  criteria  must  be  defined  to  obtain  accurate 
solutions  when  a  large  STWAVE  domain  is  partitioned.  The  following  is  a 
list  of  the  findings  of  the  sensitivity  analyses  as  well  as  recommendations 
for  defining  final  convergent  criteria: 

•  Decomposing  a  STWAVE  domain,  thereby  increasing  the  number  of 
required  processors,  results  in  substantially  decreased  wall  clock  run 
time  for  STWAVE  and  allows  for  larger  problems  to  be  solved  by 
distributing  memory  requirements. 

•  Stricter  convergence  criteria  increase  the  running  time  for  STWAVE 
when  considering  the  same  number  of  processors.  However,  the 
difference  in  wall  time  tends  to  decrease  as  the  number  of  processors 
increase. 

•  Wall  time  appears  to  be  more  sensitive  to  the  maximum  relative 
difference  parameter  (FINAL_ITERS_STOP_VALUE)  than  the 
percentage  of  cells  required  to  obtain  the  stop  value 
(FINAL_ITERS_PERCENT_VALUE) . 

•  More  iteration  is  required  when  the  maximum  relative  difference  is 
tightened  than  the  cell  percentage.  Hence,  increasing  the  relative 
difference  is  likely  more  costly  in  terms  of  time  than  increasing  the 
percentage  of  cells  required  to  obtain  the  stop  value. 

•  If  the  relative  difference  criterion  is  insufficient,  blocks  appear  in  the 
wave  field  and  indicate  the  final  solution  was  not  adequately  passed 
between  cells.  No  apparent  differences  in  overall  solution  quality  were 
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observed  between  selecting  99.5  or  99.8  as  the  cell  percentage  for 
parallel  runs. 

•  Differences  in  the  wave  field  solution  occurred  as  a  result  of  varying 
convergence  criteria  and  number  of  processors.  However,  these 
differences  appear  to  be  on  the  order  of  centimeters  and  most  likely  are 
within  an  acceptable  tolerance  considering  the  magnitude  of  the 
generated  waves. 

•  If  an  STWAVE  domain  is  going  to  be  decomposed  close  to  the 
maximum  allowed  portioning  (i.e.,  each  partition  approaches  but  does 
not  go  below  20  cells),  results  herein  indicate  an  EF  of  (0.05,  99.8) 
provides  the  results  most  closely  resembling  those  of  a  serial 
simulation.  Running  these  EF  criteria  with  more  computer  processors 
will  allow  an  adequate  and  timely  solution,  since  the  wall  times  of  the 
stricter  criteria  and  many  processors  approaches  those  of  the  relaxed 
criteria  at  a  lower  number  of  processors. 

•  For  a  domain  decomposition  resulting  in  a  smaller  number  of 
processors,  an  EF  of  (0.05,  99.5)  is  likely  to  suffice.  The  relative 
difference  is  kept  the  same  to  facilitate  value  matching  along  grid 
boundaries,  while  a  slightly  lower  cell  percentage  was  shown  to  reduce 
wall  time  and  not  significantly  impact  the  solution. 
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6  STWAVE  Spatial  Data  Sets 

STWAVE  spatial  data  sets  define  a  series  of  values  associated  with  points 
in  space,  i.e.,  (I,J)  grid  cells  or  interpolated  (x,y)  locations  within  the 
domain.  There  are  two  types  of  spatial  data  sets,  global  and  local.  Global 
data  sets  span  the  entire  computational  grid  (each  grid  cell  is  defined  a 
value)  while  local  data  sets  consist  of  values  connected  with  particular  (I,  J) 
grid  cells  or  (x,y)  locations.  Further  explanation  of  these  data  sets  is  given 
here  with  examples  of  STWAVE  global  and  local  spatial  data  sets  provided 
in  Appendix  B.  SMS  11.0+  must  have  the  following  text  on  line  1: 

“  #  STWAVE_SPATIAL- DAT  ASET,  ”  without  the  quotes. 

Spatial  data  sets  begin  with  two  namelists,  datadims  and  dataset. 
Descriptions  of  these  FORTRAN  namelists  are  given  in  Table  22  and 
Table  23. 


Table  22.  STWAVE  spatial  data  sets  -  datadims  namelist. 


Variable  Name 

Description 

Comments 

DATATYPE 

=  0  -  global  data  sets 
=  1  -  local  (l,J)  grid  cell  data  sets 
=  2  -  local  station  (x,y)  data  sets 

2  -  is  not  functional  at  this  time 

NUMRECS 

#  =  number  of  snap  IDD's 

=  lfor  time-independent  data 
sets 

NUMFLDS 

#  =  number  of  fields  per  snap  IDD 

Nl 

#  =  number  of  cells  in  the  l-direction  for  global 
data  sets 

#  =  number  of  output  points  per  snap  IDD  for 
local  data  sets 

NJ 

#  =  number  of  cells  in  the  J-direction  for  global 
data  sets 

#  =  lfor  local  data  sets 

DX 

#  =  grid  spacing  (m)  in  the  l-direction 

Not  provided  for  local  data  sets 

DY 

#  =  grid  spacing  (m)  in  the  J-direction 

Not  provided  for  local  data  sets 

GRIDNAME 

=  associated  STWAVE  grid  name 

Character  data 
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Table  23.  STWAVE  spatial  data  sets  -  dataset  namelist. 


Variable  Name 

Description 

Comments 

FLDNAME(NUMFLDS) 

=  name  of  each  field 

Character  data 

FLDUNITS(NUMFLDS) 

=  units  for  each  field 

Character  data 

RECINC 

#  =  increment  between  snap  IDD's 

RECINC  =  1  for  time-independent 
or  non-regularly  spaced  data  sets 

RECUNITS 

=  units  corresponding  to  l_TIME_INC 

Character  data 

Enter  “  “  for  integer,  alpha 
numeric,  or  snap  IDD’s  spanning 
multiple  units 

REFTIME 

=  reference  starting  time 

Character  data 

Set  as  IDDS(l) 

Global  spatial  data  sets 

Global  spatial  data  sets  cover  the  entire  scope  of  the  domain  by  assigning 
each  grid  cell  a  value.  Global  spatial  data  sets  are  either  time-dependent 
(cell  values  are  uniquely  assigned  for  every  snap  IDD)  or  time- 
independent  (every  snap  uses  one  set  of  cell  values,  provided  only  once). 
Time-dependent  spatial  data  sets  include  spatially  varying  water  level 
corrections  (SURGE),  spatially  varying  winds  (WIND),  wave  fields 
(WAVE),  peak  wave  periods  (TP),  breaking  indices  (BREAK),  and 
radiation  stresses  (RADS).  Bathymetry  (DEP)  and  bottom  friction  (FRIC) 
comprise  the  time-independent  global  spatial  data  sets.  Current  fields 
(CURR)  are  time-dependent  data  sets  for  ICUR  =  l  and  time-independent 
for  ICUR  =  2.  For  global  data  sets,  the  file  header  appears  as  follows: 

#  S  T WAVE_S  PAT I AL_DAT AS  E  T 
Sdatadims 
datatype  =  0, 
numrecs  =  #, 
numflds  =  #, 
ni  =  # , 
nj  =  #, 
dx  =  #, 
dy  =  #, 

gridname  =  "characters" 

/ 

# 

Sdataset 

fldname(l)  =  "characters", 
fldunits(l)  =  "characters", 

recinc  =  #,  (=1  if  non-regularly  spaced  or  time-independent) 

recunits  =  "characters",  (not  required  if  NUMRECS  =  1) 

reftime  =  "characters"  (not  required  if  NUMRECS  =  1) 

/ 
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The  record  data  or  grid  cell  values  follow  the  namelists  and  are  listed  as 
the  following  for  a  global  data  set  with  three  fields: 


IDD  IDDS 
field  1 

(1) 

field  2 

field  3  "I 

I 

field  1 

field  2 

field  3 

y  snap  IDDS(l) 

field  1 

field  2 

f ield_3  J 

1 

IDD  IDDS 
field  1 

(2) 

field  2 

field  3 

I 

field  1 

field  2 

field  3 

y  snap  IDDS(2) 

field  1 

field  2 

f ield_3  J 

1 

IDD  IDDS 
field  1 

(NUMRECS) 
field  2 

field  3  "I 

I 

field  1 

field  2 

field  3 

y  snap  IDDS(NUMRECS) 

field  1 

field  2 

field  3  J 

1 

If  the  record  is  time-independent,  then  the  number  of  records  is  equal  to 
one,  NUMRECS=i  and  only  one  snap  IDDS  is  listed. 


To  read  these  records,  the  file  begins  with  the  value  at  (i,NJ)  and  reads  in 
the  cross-shore  direction  (I  =  l  to  NI).  The  read  is  repeated  for  J  =  NJ-i 
following  the  cross-shore  direction  (I  =  l  to  NI),  and  progresses  to  J  =  l  as 
seen  in  the  following  FORTRAN  algorithm: 

do  j  =  NJ, 1,-1 

read  (10,*)  (data(i,j),  i  =  1,  NI) 
enddo 


Local  spatial  data  sets 

Local  spatial  data  sets  contain  values  that  are  connected  to  particular 
selected  locations,  either  (I,  J)  grid  cells  or  (x,y)  coordinates.  Only  the 
output  files  SELH  and  STATION  are  available  for  the  local  spatial  data 
sets.  The  local  spatial  data  sets  use  the  same  two  FORTRAN  namelist  as 
the  global  spatial  data  sets,  with  the  distinguishing  factor  being  the  value 
of  datatype  =  (l  or  2}. 


The  main  header  of  the  file  appears  as  follows  for  local  spatial  data  sets: 

#  STWAVE_SPATIAL_DATASET 

# 

Sdatadims 
datatype  =  {1,2}, 
numrecs  =  #, 
numflds  =  #, 
ni  =  # , 
nj  =  1, 
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gridname  =  "characters" 

/ 

# 

Sdataset 

fldname(l)  =  "characters", 
fldname(2)  =  "characters", 
fldname(3)  =  "characters", 
fldname(4)  =  "characters", 
fldunits(l)  =  "characters", 
fldunits(2)  =  "characters", 
fldunits(3)  =  "characters", 
fldunits(4)  =  "characters", 
recinc  =  #  a  number, 
recunits  =  "characters", 
reftime  =  "characters" 

/ 

The  data  in  a  local  spatial  data  sets  are  arranged  slightly  different  from 
global  data  sets.  For  local  spatial  data  sets,  the  snap  IDD  identifier  does 
not  separate  the  records  but  instead  serves  as  the  first  field  value,  as  seen 
in  the  next  paragraph.  The  number  of  times  a  snap  IDD  appears  depends 
on  the  number  of  selected  output  points  (NI).  This  arrangement  makes  it 
easy  to  load  the  data  records  into  a  spreadsheet  and  sort  the  data  on  any 
field  with  the  snap  IDDS  still  attached. 

IDDS(l)  field  1  field  2  field  3 

IDDS(l)  field  1  field  2  field  3 

IDDS (2)  field  1  field  2  field  3 

IDDS (2)  field  1  field  2  field  3 

IDDS (NUMRECS)  field_l  field_2  field_3 
IDDS (NUMRECS)  field  1  field  2  field  3 


snap  IDDS(NUMRECS) 
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7  STWAVE  Spectral  Data  Sets 

Incident  2-D  wave  spectra  are  specified  in  energy  density  as  a  function  of 
frequency  and  direction  (units  of  m2/Hz/radians).  The  input  spectra  can 
be  specified  at  single  or  multiple  points  along  a  boundary.  Generally,  it  is 
good  practice  to  establish  the  offshore  boundary  of  the  bathymetry  grid 
along  a  constant  depth  contour,  particularly  when  a  single  input  spectrum 
is  applied  along  the  entire  offshore  boundary.  Spectral  data  sets  have  one 
namelist,  datadims,  which  is  described  in  further  detail  in  Table  24.  The 
SPEC,  NEST,  and  OBSE  spectral  data  sets  are  described  in  Table  24  with 
examples  provided  in  Appendix  C.  SMS  11.0+  must  have  the  following  text 
on  line  1:  “ # STWAVE_SPETRAL__D ATASET, ”  without  the  quotes. 


Table  24.  STWAVE  spectral  data  sets  -  Datadims  namelist. 


Variable  Name 

Description 

Comments 

DATATYPE 

=  0  -local  station  (x,y)  locations 
=  1  -  grid  cell  (l,J)  locations 

Provided  only  for  output  files 

NUMRECS 

#  =  number  of  snap  IDD's 

NUMFREQ 

#  =  number  of  frequency  bins 

Determines  how  finely  the  calculated 
spectra  are  resolved 

Large  number  increases  computation  time 
and  a  small  number  reduces  model 

resolution 

20-30  bins  typically  used 

NUMANGLE 

#  =  number  of  angle  bands 

Defines  angular  resolution 
=  35  required  for  half-plane  simulations  (5- 
deg  resolution  in  direction)  and  72  is  typical 
for  full-plane  simulations 

NUMPOINTS 

#  =  number  of  spatial  locations  providing  data 

AZIMUTH 

#  =  the  azimuth  (rotation)  of  the  grid  in  degrees 

Real  number 

COORD_SYS 

=  name  of  the  coordinate  system  the  inputs  are 
listed  in 

‘STATEPLANE’  -  State  Plane 

'LOCAL’  -  local  coordinates 

'UTM'  -  Universal  Transverse  Mercator 

SPZONE 

#  =  state  plane  zone  code  FIPS  number 

#=  UTM  zone 

Only  needed  for  State  Plane  and  UTM 
coordinate  system 

RECUNITS 

=  units  corresponding  to  l_TIME_INC 

Character  data  (4  characters  max) 

Set  as  LTIMEJNCJJNITS  for  output  files 

Not  needed  for  SPEC  input 

REFTIME 

=  reference  starting  time 

Character  data  (20  characters  max) 

Set  as  IDDS(l)  for  output  files 

Not  needed  for  SPEC  input 
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The  main  header  of  the  spectral  files  appear  as  follows: 


(not  required  for  SPEC  file) 


#STWAVE_SPECTRAL_DATASET 
Sdatadims 
datatype  =  {0,1}, 
numrecs  =  #, 
numfrew  =  #, 
numangle  =  #, 
numpoints  =  #, 
azimuth  =  #, 

coord_sys  =  "characters", 
spzone  =  #, 

recunits  =  "characters",  (not  required  for  SPEC  file) 

reftime  =  "characters"  (not  required  for  SPEC  file) 

/ 


The  next  section  of  the  SPEC  file  specifies  the  frequencies  for  model 
spectra  (used  for  the  input  spectra,  internal  computations,  and  output 
spectra),  starting  from  the  lowest  frequency.  There  must  be  NUMFREQ 
frequencies  specified.  These  frequencies  should  span  the  frequency  range 
where  significant  wave  energy  is  contained  in  the  spectrum;  a  good  rule  is 
that  the  minimum  frequency  is  o.5*fp  and  the  maximum  frequency  is  2*fp 
where  fp  is  the  spectral  peak.  Wave  frequencies  outside  the  frequency  bin 
range  will  not  be  resolved  by  the  model. 


The  Frequencies  section  is  read  in  free  format  in  the  following  manner: 


#Frequencies 
(freq(k),  k=l, NUMFREQ) 

# 

Spectral  identifiers  are  grouped  first  by  snap  IDD  and  then  by  location. 

SPEC  files 

Following  the  Frequencies  section  is  a  header  line  containing  the  snap 
IDD,  wind  information,  peak  frequency,  water  elevation  adjustment,  and 
the  (x,y)  point  coordinates.  This  header  line  is  read  in  free  format  and  is 
followed  by  the  energy  densities  in  m2/Hz/radians.  The  spectrum  is  read 
by  reading  the  energy  densities  for  all  the  wave  directions  associated  with 
the  lowest  frequency,  and  then  reading  energy  densities  for  all  directions 
for  the  next  lowest  frequency,  etc.  For  half-plane  mode,  the  wave 
directions  begin  at  -85°  and  increase  in  50  increments  to  85°.  For  full-plane 
mode,  the  wave  directions  begin  at  o°  and  increase  in  (36o°/NUMANGLE) 
degree  increments  to  3550.  The  spectra  are  read  in  the  following  format: 
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loop  over  IDDS ( 1-NUMRECS) 
loop  over  point  locations  n  (1-NUMPOINTS) 
IDDS, UMAG, UDIR, FM, DADD, XCOOR (n) , YCOOR (n) 

( (e ( k, 1, n) , 1~1 , NUMANGLE) , k  =  1 , NUMFREQ) 
end  loop  over  point  locations  (1-NUMPOINTS) 
end  loop  over  IDDS ( 1_NUMRECS) 


where: 


UMAG  =  wind  speed  in  meters/second 

UDIR  =  wind  direction  relative  to  STWAVE  coordinate  system  in  degrees 
FM  =  peak  spectral  frequency  in  Hz 

DADD  =  elevation  adjustment  in  meters  relative  to  bathymetry  datum 
(XCOOR,  YCOOR)  =  point  location 

In  the  half-plane  version  of  the  code  boundary  spectrum  input  are  allowed 
only  on  a  single  side,  the  seaward  side,  of  the  domain.  In  the  full-plane 
version,  boundary  spectrum  inputs  are  allowed  to  be  defined  on  any  side, 
but  are  currently  restricted  to  a  single  side.  This  restriction  will  be 
eliminated  in  future  releases. 

OBSEand  NEST  file 

Wave  spectra  at  selected  grid  cells,  specified  in  the  *.sim  file,  are  saved  to 
spectral  output  files.  Similar  to  the  SPEC  input  file,  this  file  begins  with  a 
header  which  is  followed  by  the  frequencies.  Following  the  Frequencies 
section  is  a  header  line  containing  the  snap  IDD,  wind  information,  water 
level  adjustment,  and  selected  output  (I,J)  grid  location.  The  energy 
density  values  are  in  m2/Hz/radians.  The  spectra  are  written  starting  with 
the  lowest  frequency  and  writing  energy  density  for  all  wave  directions, 
followed  by  the  energy  density  for  all  wave  directions  for  the  next  lowest 
frequency,  etc.  The  spectra  are  written  in  an  order  based  on  the  I-cell 
index,  starting  from  smallest  index  and  proceeding  to  the  largest  index. 
The  spectra  are  written  in  the  following  format: 

loop  over  IDDS ( 1-NUMRECS) 
loop  over  grid  locations  (1-NUMPOINTS) 

IDDS, UMAG, UDIR, FM, DADD, IOUT,  JOUT 
(e (k,  1,  JOUT,  IOUT) , 1=1, NUMANGLE) , k  =  1, NUMFREQ) 
end  loop  over  grid  locations  (1-NUMPOINTS) 
end  loop  over  IDDS ( 1-NUMRECS) 


where  IOUT  =  I-grid  location  and  JOUT  =  J-grid  location. 
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Appendix  A:  Example  STWAVE_SIM  JFILE 


#  S TWAVE_ S I M_ FILE 

#  STWAVE  Model  Parameter  Input  File 

# 

#  METADATA  SECTION  -  A  user  can  enter  any  information 

#  desired  within  this  first  block  of  comments,  provided  the 

#  first  character  of  each  line  is  a  "#"  symbol.  Note  that 

#  SMS  requires  the  first  line  to  be  as  is  given  above,  but 

#  subsequent  lines  can  be  any  other  comments. 

# 

############################################## 

# 

#  Standard  Input  Section 

# 

&std_parms 
iplane  =  1, 
iprp  =  0, 
icur  =  0, 
ibreak  =  1, 
irs  =  1, 
nselct  =  10, 
nnest  =  4, 
nstations  =  3, 
ibnd  =  1, 
ifric  =  4, 
isurge  =  1, 
iwind  =  1, 
idep_opt  =  0, 
i_bcl  =  2, 
i_bc2  =  3, 
i_bc3  =  0, 
i_bc4  =  3 

/ 


#  Runtime  Parameters  Section 

# 

&run_parms 
idd_spec_type  =  1, 
numsteps  =  25, 
n_grd_part_i  =  3, 
n_grd_part_j  =  4, 
n_init_iters  =  20, 
init_iters_stop_value  =  0.10, 
init_iters_stop_percent  =  100.0, 
n_f inal_iters  =  20, 
f inal_iters_stop_value  =  0.10, 
f inal_iters_stop_percent  =  99.8, 
default_input_io_type  =  1, 
default_output_io_type  =  1 

/ 


#  Spatial  Grid  Parameters  Section 

# 

&spatial_grid_parms 
coord_sys  =  ' STATEPLANE ' , 
spzone  =  1703, 
xO  =  1360620.0, 
yO  =  504124.0, 
azimuth  =  90.0, 
dx  =  200.0, 
dy  =  200.0, 
n  cell  i  =  683, 
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n_cell_j  =750 

/ 

# 

#  Input  Files  Section 

# 

&input_f iles 
DEP  =  "MS-AL.dep", 

SURGE  =  "MS-AL . surge . in" , 
SPEC  =  "MS-AL. eng", 

WIND  =  "MS-AL. wind. in", 

FRIC  =  "MS-AL . friction . in" , 
io_type_dep  =  1, 
io_type_surge  =  1, 
io_type_wind  =  1, 
io_type_spec  =  1, 
io_type_fric  -  1 

/ 


#  Output  Files  Section 


&output_f iles 
WAVE  =  "MS-AL . wave . out" , 

OBSE  =  "MS-AL. obse. out", 

BREAK  =  "MS-AL. break. out", 

RADS  =  "MS-AL. rads .out", 

SELH  =  "MS-AL. selh. out", 
STATION  =  "MS-AL. station. out", 
NEST  =  "MS-AL. nest. out", 

LOGS  =  "MS-AL. log. out", 

TP  =  "MS-AL. Tp. out" 
io_type_tp  =  1, 
io_type_nest  =  1, 
io_type_selh  =  1, 
io_type_rads  =  1, 
io_type_break  =  1, 
io_type_obse  =  1, 
io_type_wave  =  1 , 
io_type_station  =  1 

/ 


#  Time  Parameters  Section 

# 

&time_parms 
i_time_inc  =  30, 
i_time_inc_units  =  'mm', 
iyear_start  =  2001, 
imon_start  =  08, 
iday_start  =  06, 
ihr_start  =  07, 
imin_start  =  15, 
isec_start  =  00, 
iyear_end  =  2010, 
imon_end  =  08, 
iday_end  =  06, 
ihr_end  =  08, 
imin_end  =  45, 
isec_end  =  0 

/ 


A 


Required  for  IDD_SPEC_TYPE  =  ±2  or  ±3. 

When  IDD_SPEC_TYPE  =  2,  all  units  are 
required. 

When  IDD_SPEC_TYPE  =  3,  then  LTIMEJNC 
and  l_TIMEJNC_UNITS  are  the  only  required 
units. 

When  IDD_SPEC_TYPE  =  -2  or  -3, 
l_TIMEJNC_UNITS  is  the  only  required  units. 


J 


# 

#  Constant  Boundary  Spectrum  Information 

# 

&const_spec 
nfreq  =  30, 
na  =  72, 
fO  =  0.05, 
df_const  =  0.02 

/ 


The  time_parms, 
constant_spec,  depth_fun,  and 
constant_fric  namelists  are 
potentially  optional,  depending 
on  user  inputs  in  the  primary 
namelists.  However,  the  order  in 
which  they  appear  is  fixed. 
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#  Analytic  Depth  Profile 

# 

&depth_fun 
dp_iside  =  1, 
dp_dl  =  20.0, 
dp_slope  =  0.10 

/ 

# 

#  Constant  Bottom  Friction  Value 


The  following  bold  “extra”  namelists  are 
potentially  optional,  depending  on  user  inputs  in 
the  primary  namelists.  However,  the  order  in 
which  they  appear  is  fixed.  Notice  the  “extra” 
namelists  start  with  an  instead  of  an 


&const_f ric 
cf_const  =  0.01 

/ 

# 

#  Snap  IDDs 

# 

@snap_idds 
idds  (1)  = 
idds (2)  = 
idds (3)  = 


9120800, 

9310125, 

9310205, 


idds (numsteps) 

/ 

# 

#  Select  Point  Data 

# 

@select_pts 
iout(l)  =  10,  jout( 
iout(2)  =  125,  jout 


Required  for  IDD_SPEC_TYPE  =  1,  -2,  -3,  or  4. 

If  1DD_SPEC_TYPE  =  1,  then  the  values  are 
integers. 

If  IDD_SPEC_TYPE  =  -2  or  -3,  then  the  values 
are  non-regularly  spaced  time  data  enclosed 
in  single  quotes. 

If  IDD_SPEC_TYPE  =  4,  then  the  values  are 
alpha  numeric  characters  (max  20 
characters)  enclosed  in  single  quotes. 

Must  appear  as  a  single  entry  per  row  (i.e. 
one  column). 

74, 

201  . 

iout (nselct) ,  jout(nselct) 

/ 

# 

#  Nest  Point  Data 

# 

@nest_pts 

inest(l)  =  78,  jnest(l)  =  176, 
inest(2)  =  94,  jnest(2)  =  67, 

inest (nnest) ,  jnest(nnest) 

/ 

# 

#  Station  Location  Data 

# 

@station_locations 

stat_xcoor (1)  =  1361620.0,  stat_ycoor (1)  =  502124.0, 
stat_xcoor (2)  =  1362820.0,  stat_ycoor (2)  =  502324.0, 


Must  appear  as  two  column  pairs. 


stat_xcoor (nstations) ,  stat_ycoor (nstations) 

/ 

# 

#  Spatially  Constant  Winds 

# 

@const_wind 

umag_const_in (1)  =  2.9,  udir_const_in (1)  =  0.0, 
umag_const_in (2)  =  3.1,  udir_const_in (2)  =  12.0, 
umag_const_in (3)  =  3.2,  udir_const_in (3)  =  15.6, 

umag_const_in (numsteps) ,  udir_const_in (numsteps) 

/ 

# 

#  Spatially  Constant  Water  Level  Adjustment 

#  _ 

@const_surge 

dadd_const_in ( 1 )  =0.2, 
dadd  const  in (2)  =  0.8, 


Must  appear  as  two 
column  pairs. 


Must  appear  as  a  single  entry 
per  row  (i.e.  one  column). 


ra  =8:  =8=  =8= 
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dadd_const_in (3)  =  1.17, 


dadd_const_in (numsteps) 

/ 


Constant  Boundary  Spectra 

cons  t_tma_spec 
h_spec_in (1 , 1)  =  0 . 34 , tp_spec_in (1 , 1) 
h_spec_in (2 , 1)  =  0 . 85 , tp_spec_in (2 , 1) 
h  spec  in(3,l)  =  0.42,tp_spec  in(3,l) 


Must  appear  as  three  column  triplets. 


1 . 84 ,wvang_spec_in (1 , 1)  =  0.34, 

1 . 96 ,wvang_spec_in (2 , 1)  =  36.6, 

1 . 67 ,wvang_spec  in (3,1)  =  358.5, 


h_spec_in (numsteps , iside) , tp_spec_in (numsteps , iside) , 
wvang_spec_in= (numsteps , iside) 

/ 
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Appendix  B:  Example  STWAVE  Spatial  Files 

Global  Input:  DEP  File 

#  S  T WAVE_S  PAT I AL_DAT AS  E  T 

Sdatadims 

datatype  =  0, 
numrecs  =  1, 
numflds  =  1, 
ni  =  683, 
nj  =  750, 
dx  =  200.0, 
dy  =  200.0, 
gridname  =  "MS-AL" 

/ 

# 

Sdataset 

fldname(l)  =  "Depth", 
fldunits(l)  =  "m", 
recinc  =  1 

/ 

IDD  constant  values 
13.48482200000000 
13.26323800000000 
13.00494800000000 
12.71821700000000 
12.42996800000000 
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Global  Input:  SURGE  File 

#  S  T WAVE_S  PAT I AL_DAT AS  E  T 

Sdatadims 

datatype  =  0, 
numrecs  =  93, 
numflds  =  1, 
ni  =  255, 
nj  =  360, 
dx  =  200.0, 
dy  =  200.0, 
gridname  =  "SE" 

/ 

# 

Sdataset 

fldname(l)  =  "Surge", 
fldunits(l)  =  "m", 
recinc  =  20, 
recunits  =  "mm", 
reftime  =  "20090815043000" 

/ 

IDD  20090815043000 
0.3593712000000000 
0.3598506000000000 
0.3603262000000000 

IDD  20090815045000 
0.43196110 
0.43210700 
0.43225290 
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Global  Input:  WIND  File 

#  S  T WAVE_S  PAT I AL_DAT AS  E  T 

Sdatadims 

datatype  =  0, 
numrecs  =  25, 
numflds  =  2, 
ni  =  683, 
nj  =  750, 
dx  =  200.0, 
dy  =  200.0, 
gridname  =  "MS-AL" 

/ 

# 

Sdataset 

fldname(l)  =  "Wind  Speed", 
fldname(2)  =  "Wind  Direction", 
fldunits(l)  =  "m/s", 
fldunits(2)  =  "deg", 
recinc  =  1, 
recunits  = 
reftime  = 

/ 

IDD  9120800 
3.1  34.02 
3.5  37.15 

IDD  9310125 
3.7  42.30 
4.0  43.07 


9120800 
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Global  Input:  FRIC  File 

#  S  T WAVE_S  PAT I AL_DAT AS  E  T 

Sdatadims 

datatype  =  0, 
numrecs  =  1, 
numflds  =  1, 
ni  =  683, 
nj  =  750, 
dx  =  200.0, 
dy  =  200.0, 
gridname  =  "MS-AL" 

/ 

# 

Sdataset 

fldname(l)  =  "Friction", 
f ldunits ( 1 )  =  "  ", 
recinc  =  1 

/ 

IDD  constant  values 
2.000E-002 
2 . 000E-002 
2 . 000E-002 
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Global  Input:  CURR  File 

#  S  TWAVE_S PAT I AL_DAT AS  E  T 

Sdatadims 

datatype  =  0, 
numrecs  =  93, 
numflds  =  2, 
ni  =  255, 
nj  =  360, 
dx  =  200.0, 
dy  =  200.0, 
gridname  =  "SE" 

/ 

# 

Sdataset 

fldname(l)  =  "Current  -  u", 
fldname(2)  =  "Current  -  v", 
fldunits(l)  =  "m/s", 
fldunits(2)  =  "m/s", 
recinc  =  20, 
recunits  =  "mm", 
reftime  =  "20090815043000" 

/ 

IDD  20090815043000 
-0.074441  0.521558 
-0.075095  0.522148 
-0.075748  0.522737 

IDD  20090815045000 
-0.079451  0.563457 
-0.080005  0.564618 
-0.080271  0.565907 
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Global  Output:  WAVE  File 

#  S  TWAVE_S PAT I AL_DAT AS  E  T 

Sdatadims 

datatype  =  0, 
numrecs  =  15, 
numflds  =  3, 
ni  =  832, 
ni  =  824, 
dx  =  200.0, 
dy  =  200.0, 

GridName  =  "S  sim" 

/ 

# 

Sdataset 

fldname(l)  =  "Wave  Height", 
fldname(2)  =  "Wave  Period", 
fldname(3)  =  "Wave  Direction", 
fldunits(l)  =  "m", 
fldunits(2)  =  "sec", 
fldunits(3)  =  "deg", 
recinc  =  1, 
recunits  =  "hh", 
reftime  =  "20010806071500" 

/ 

IDD  20010806071500 
0.51  10.1  99.9 
0.51  10.2  100.0 
0.50  10.1  100.0 

IDD  20010806081500 
0.65  10.2  98.0 
0.66  10.2  98.0 
0.66  10.2  97.8 
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Global  Output:  BREAK  File 

#  S  TWAVE_S PAT I AL_DAT AS  E  T 

Sdatadims 

datatype  =  0, 
numrecs  =  93, 
numflds  =  1, 
ni  =  255, 
nj  =  360, 
dx  =  200.0, 
dy  =  200.0, 

GridName  =  "SE" 

/ 

# 

Sdataset 

fldname (  1)  =  "Breaking", 
fldunits (  1)  =  "n/a", 
recinc  =  20, 
recunits  =  "mm", 
reftime  =  "20090815043000" 

/ 

IDD  20090815043000 
0 
0 
0 
0 

IDD  20090815045000 
0 
0 
0 
0 
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Global  Output:  RADS  File 

#  S  TWAVE_S PAT I AL_DAT AS  E  T 

Sdatadims 

datatype  =  0, 
numrecs  =  25, 
numflds  =  2, 
ni  =  683, 
nj  =  750, 
dx  =  200.0, 
dy  =  200.0, 
gridname  =  "MS-AL" 

/ 

# 

Sdataset 

fldname(l)  =  "Radstress  -  x", 

fldname(2)  =  "Radstress  -  y", 

fldunits(l)  =  "n/a", 

fldunits(2)  =  "n/a", 

recinc  =  1, 

recunits  =  "n/a", 

reftime  =  "9120800" 

/ 

IDD  9120800 

3 . 1321E-005  -1 . 2595E-005 
-3 . 9486E-005  -8.1486E-006 

IDD  9310125 

3 . 9874E-005  -2.2227E-005 
-6 . 758E-005  -7.0401E-006 
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Local  Selected  Points  (l,J) :  SELH  File 

#  S  TWAVE_S PAT I AL_DAT AS  E  T 
Sdatadims 

datatype  =  1, 
numrecs  =  93, 
numflds  =  6, 
ni  =  5 , 
nj  =  1, 

gridName  =  "SE" 

/ 

# 

Sdataset 


f ldname ( 1 ) 

=  "  IDD" , 

f ldname (2 ) 

=  "i-cell". 

f ldname ( 3 ) 

=  "j-cell". 

f ldname ( 4 ) 

=  "Wave  Height", 

f ldname ( 5 ) 

=  "Wave  Period", 

f ldname (6) 

=  "Wave  Direction 

f ldunits  ( 1 ) 

=  "n/a". 

f ldunits  (2 ) 

=  "n/a"  , 

f ldunits ( 3 ) 

=  "n/a"  , 

f ldunits  ( 4 ) 

=  "m". 

f ldunits ( 5 ) 

=  "sec". 

f ldunits (6) 

=  "deg". 

recinc  =  20 

r 

recunits  = 

"mm" , 

reftime  =  " 

20090815043000" 

20090815043000 

20090815043000 

20090815043000 

20090815043000 

20090815043000 

20090815045000 

20090815045000 

20090815045000 

20090815045000 

20090815045000 


10  74  1.71  7.86  5.54 

11  128  1.76  7.63  10.4 
27  55  0.00  2.97  13.3 
82  264  0.74  3.03  -5.0 
161  273  0.25  2.25  2.56 

10  74  1.73  7.36  4.84 

11  128  1.78  7.85  9.56 
27  55  0.05  3.00  15.7 
82  264  0.80  3.01  -2.9 
161  273  0.29  2.23  2.0 
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Local  Stations  ( x,y ):  STATION  File 

#  S  TWAVE_S PAT I AL_DAT AS  E  T 
Sdatadims 

datatype  =  1, 
numrecs  =  93, 
numflds  =  6, 
ni  =  2 , 
nj  =  1, 

gridName  =  "SE" 

/ 

# 

Sdataset 


f ldname ( 1 ) 

=  "  IDD" , 

f ldname (2 ) 

=  "i-cell". 

f ldname ( 3 ) 

=  "j-cell". 

f ldname ( 4 ) 

=  "Wave 

Height" , 

f ldname ( 5 ) 

=  "Wave 

Period" , 

f ldname (6) 

=  "Wave 

Direction 

f ldunits  ( 1 ) 

_  1!  II 

t 

f ldunits  (2 ) 

_  II  II 

r 

f ldunits ( 3 ) 

_  ii  ii 

r 

f ldunits  ( 4 ) 

=  "m", 

f ldunits ( 5 ) 

=  "sec" 

r 

f ldunits (6) 

=  "deg" 

r 

recinc  =  20 

r 

recunits  = 

"mm" , 

reftime  =  " 

20090815043000" 

/ 


20090815043000 

28.50 

29.00 

LO 

o 

10.1 

100.0 

20090815043000 

30.00 

30.20 

0.5 

10.1 

100.0 

20090815045000 

40.75 

32.35 

0.5 

10.1 

100.0 

20090815045000 

28.50 

29.00 

0.7 

10.2 

98.0 
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Appendix  C:  Example  STWAVE  Spectral  Files 

SPEC  File 

#STWAVE_SPECTRAL_DATASET 
Sdatadims 
Datatype  =  0 
numrecs  =  25, 
numfreq  =  28, 
numangle  =  72, 
numpoints  =  10, 
azimuth  =  108.0, 
coord_sys  =  "STATEPLANE" , 
spzone  =  1703,  RecUnits  =  "n/a" 

Reftime  -  "9120800" 

/ 

#Frequencies 

3 . 139999E-02  3.449999E-02  3.799999E-02  4.180000E-02  4.589999E-02 
5 . 050000E-02  5.559999E-02  6.120000E-02  6.729999E-02  7.400000E-02 
8 . 140000E-02  8 . 950000E-02  9.849999E-02  0.108300  0.119200 
0.131100  0.144200  0.158600  0.174500  0.191900 
0.211100  0.232300  0.255500  0.281000  0.309100 
0.340000  0.374000  0.411400 

# 

9120800  13.71  80.  0.0740  0.0000  1360620.88  504123.88 
0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000 

0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000 

0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000 

0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000 

9120800  13.51  79.8  0.0740  0.0000  1361620.88  502123.88 

0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000 

0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000 

0.110  0.15  0.100  0.001  0.001  0.000  0.000  0.000  0.000  0.000  0.000  0.000 
0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.068 
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OBSE  and  NEST  File 

#STWAVE_SPECTRAL_DATASET 

Sdatadims 
numrecs  =  25, 
datatype  =  1, 
numfreq  =  28, 
numangle  =  72, 
numpoints  =  1, 
azimuth  =108.0, 
coord_sys  =  "STATEPLANE" , 
spzone  =  1703 
recunits  =  "n/a", 
reftime  =  "9120800" 

/ 

#Frequencies 

3 . 139999E-02  3.449999E-02  3.799999E-02  4.180000E-02  4.589999E-02 
5 . 050000E-02  5.559999E-02  6.120000E-02  6.729999E-02  7.400000E-02 
8 . 140000E-02  8 . 950000E-02  9.849999E-02  0.108300  0.119200 
0.131100  0.144200  0.158600  0.174500  0.191900 
0.211100  0.232300  0.255500  0.281000  0.309100 
0.340000  0.374000  0.411400 

# 

9120800  13.71  80.  0.0740  0.0000  2  40 

0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.00000 

0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.00000 

0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.00000 

0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.00000 

0.00000  0.00000  0.00000  0.00000 

9310125  13.71  80.  0.0740  0.0000  2  40 
0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.00000 

0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.00000 

0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.00000 

0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.00000 

0.00000  0.00000  0.00000  0.00000 
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